Merge pull request #1 from mongodb-labs/README-fixes

Small Fixes

Author: Jibola

.github/FUNDING.yml

@@ -95,7 +95,7 @@ The tests are broken and it would be great if someone could take that on. Other
 
 See notes: 
 
-## 0.1.0
+## CalVer 2023.11.10
 
 - Replaced Next/Vue.js frontend framework with entirely React/Redux
 - Replaced Backend native connection of PostgreSQL/SQLAlchemy with MongoDB Motor/Beanie ODM

README.md

@@ -22,7 +22,7 @@ Go to the directory where you want to create your project and run:
 
 ```bash
 pip install cookiecutter
-cookiecutter https://github.com/whythawk/full-stack-fastapi-postgresql
+cookiecutter https://github.com/mongodb-labs/full-stack-fastapi-mongodb.git
 ```
 
 ## Generate passwords
@@ -38,7 +38,7 @@ Copy the contents and use that as password / secret key. And run that again to g
 
 ## Input variables
 
-The generator (Cookiecutter) will ask you for data on a long list of fields which will be used to populate variables across the project, customising it for you out the box. You might want to have these on hand before generating the project.
+The generator (Cookiecutter) will ask you for data on a long list of fields which will be used to populate variables across the project, customising it for you out the box. **You might want to have these on hand before generating the project.**
 
 The input variables, with their default values (some auto generated) are:
 
@@ -53,7 +53,7 @@ The input variables, with their default values (some auto generated) are:
 - `secret_key`: Backend server secret key. Use the method above to generate it.
 - `first_superuser`: The first superuser generated, with it you will be able to create more users, etc. By default, based on the domain.
 - `first_superuser_password`: First superuser password. Use the method above to generate it.
-- `backend_cors_origins`: Origins (domains, more or less) that are enabled for CORS (Cross Origin Resource Sharing). This allows a frontend in one domain (e.g. `https://dashboard.example.com`) to communicate with this backend, that could be living in another domain (e.g. `https://api.example.com`). It can also be used to allow your local frontend (with a custom `hosts` domain mapping, as described in the project's `README.md`) that could be living in `http://dev.example.com:8080` to communicate with the backend at `https://stag.example.com`. Notice the `http` vs `https` and the `dev.` prefix for local development vs the "staging" `stag.` prefix. By default, it includes origins for production, staging and development, with ports commonly used during local development by several popular frontend frameworks (Vue with `:8080`, React, Angular).
+- `backend_cors_origins`: Origins (domains, more or less) that are enabled for CORS ([Cross Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)). This informs a frontend browser in one domain (e.g. `https://dashboard.example.com`) it can trust this backend, that could be living in another domain (e.g. `https://api.example.com`). It can also be used to allow your local frontend (with a custom `hosts` domain mapping, as described in the project's `README.md`) that could be living in `http://dev.example.com:8080` to communicate with the backend at `https://stag.example.com`. Notice the `http` vs `https` and the `dev.` prefix for local development vs the "staging" `stag.` prefix. By default, it includes origins for production, staging and development, with ports commonly used during local development by several popular frontend frameworks (Vue with `:8080`, React, Angular).
 - `smtp_port`: Port to use to send emails via SMTP. By default `587`.
 - `smtp_host`: Host to use to send emails, it would be given by your email provider, like Mailgun, Sparkpost, etc.
 - `smtp_user`: The user to use in the SMTP connection. The value will be given by your email provider.

docs/development-guide.md

@@ -45,7 +45,7 @@ This FastAPI, React, MongoDB repo will generate a complete web application stack
 
 ## Who is it for?
 
-This project is a rock-solid foundation on which to build complex web applications which need parallel processing, scheduled event management, and a range of relational and graph database support. The base deployment requires about 2Gb of memory to run. 
+This project is a rock-solid foundation on which to build complex web applications which need parallel processing, scheduled event management, leveraging a NoSQL Datastore (MongoDB). The base deployment requires about 2Gb of memory to run. 
 
 This is **not** a light-weight system to deploy a blog or simple content-management-system.
 
@@ -83,9 +83,9 @@ Running Cookiecutter to customise the deployment with your settings, and then bu
 
 ### Setting up a Mongo Connection
 
-A Mongo connection can be set up one of two ways: At the cookiecutter generation step, provide the `mongodb_uri`, and `mongo_database` to inform the generator on how to connect to an Atlas cloud instance. Additionally, in the generated file, you can manually set the .env.MONGO_DATABASE_URI and it will connect to the Atlas cluster made locally.
+A Mongo connection can be set up one of two ways: At the cookiecutter generation step, provide the `mongodb_uri`, and `mongo_database` to inform the generator on how to connect to an Atlas cloud instance. Additionally, in the generated file, you can manually leave the `.env.MONGO_DATABASE_URI` as `mongodb` and it will automatically connect to the running mongodb docker instance.
 
-Additionally, developers could configure a local mongo instance, but it would either have to be spun up in docker, or generated separately and also allow for non-localhost connections to be made.
+Whilst the local instance is available, it is best advised to create or [connect to a MongoDB Atlas Cluster](https://www.mongodb.com/docs/atlas/tutorial/connect-to-your-cluster/).
 
 ### Deploying for production
 
@@ -105,7 +105,7 @@ After using this generator, your new project will contain an extensive `README.m
 
 ## Release Notes
 
-### 0.1.0
+### 2023.11.10
 - Experimental release of FARM-stack generator app
 
 ## License

docs/getting-started.md

@@ -44,16 +44,16 @@ If your Docker is not running in `localhost` (the URLs above wouldn't work) chec
 **The backend and celery containers will fail to load if a proper Mongo URI is not configured**.
 
 Please ensure that either 
-- `MONGO_(HOST|USER|PASSWORD|DATABASE)` were properly set in the initial MongoDB setup phase
-- `MONGO_DATABASE_URI` has been set in `{{ cookiecutter.project_slug }}/.env`
+- `MONGO_DATABASE` is properly set in the initial Cookiecutter setup phase.
+- `MONGO_DATABASE_URI` has been set in `{{ cookiecutter.project_slug }}/.env`; leaving the initial value as `mongodb` will establish a connection to the docker instance of mongo created.
 
 To learn more about how to generate a MongoDB URI please look at the docs on [Connecting to your MongoDB Atlas Clutser](https://www.mongodb.com/docs/atlas/tutorial/connect-to-your-cluster/)
 
 ### Setting Up MongoDB Locally
 
-**Currently, the FARM-stack generator does not provide a running `mongod` within the docker container**
+The docker-compose file has a simple setup for a mongodb server to run in a docker container. It'll be exposed on port `27017` and reachable by setting the MONGO_DATABASE_URI to `mongodb`
 
-If running a local instance of MongoDB outside of a docker container that you want your backend to communicate with, you will need to set up [port forwarding in your docker config](https://docs.docker.com/desktop/networking/#use-cases-and-workarounds). Since the intention of this generator is to work with scalable production environments very quickly, providing a local container of MongoDB was not part of the initial charter in its creation. **We do strongly advise you connect to an Atlas cluster** 
+Since the intention of this generator is to work with scalable production environments very quickly, we provide a container of MongoDB, but **We do strongly advise you connect to an Atlas cluster** 
 
 To see how to use MongoDB with Docker, read through this article on [set-up steps](https://www.mongodb.com/compatibility/docker)
 
@@ -635,6 +635,8 @@ Github Actions is configured assuming 2 environments following Github flow:
 
 If you need to add more environments, for example, you could imagine using a client-approved `preprod` branch, you can just copy the configurations in `actions.yml` for `stag` and rename the corresponding variables. The Docker Compose file and environment variables are configured to support as many environments as you need, so that you only need to modify `actions.yml` (or whichever CI system configuration you are using).
 
+Support for the deployment to the desired host domain has been commented out as the functionality has not been tested by the MongoDB team. Feel free to uncomment and follow instructions for deployment steps at your own discretion.
+
 ## Docker Compose files and env vars
 
 There is a main `docker-compose.yml` file with all the configurations that apply to the whole stack, it is used automatically by `docker-compose`.
@@ -773,7 +775,7 @@ This project was generated using https://github.com/mongodb-labs/full-stack-fast
 
 ```bash
 pip install cookiecutter
-cookiecutter https://github.com/whythawk/full-stack-fastapi-mongodb
+cookiecutter https://github.com/mongodb-labs/full-stack-fastapi-mongodb.git
 ```
 
 You can check the variables used during generation in the file `cookiecutter-config-file.yml`.

{{cookiecutter.project_slug}}/README.md

@@ -55,19 +55,20 @@ If your Docker is not running in `localhost` (the URLs above wouldn't work) chec
 **The backend and celery containers will fail to load if a proper Mongo URI is not configured**.
 
 Please ensure that either 
-- `MONGO_(HOST|USER|PASSWORD|DATABASE)` were properly set in the initial MongoDB setup phase
-- `MONGO_DATABASE_URI` has been set in `{{ cookiecutter.project_slug }}/.env`
+- `MONGO_DATABASE` is properly set in the initial Cookiecutter setup phase.
+- `MONGO_DATABASE_URI` has been set in `{{ cookiecutter.project_slug }}/.env`; leaving the initial value as `mongodb` will establish a connection to the docker instance of mongo created.
 
 To learn more about how to generate a MongoDB URI please look at the docs on [Connecting to your MongoDB Atlas Clutser](https://www.mongodb.com/docs/atlas/tutorial/connect-to-your-cluster/)
 
 ### Setting Up MongoDB Locally
 
-**Currently, the FARM-stack generator does not provide a running `mongod` within the docker container**
+The docker-compose file has a simple setup for a mongodb server to run in a docker container. It'll be exposed on port `27017` and reachable by setting the MONGO_DATABASE_URI to `mongodb`
 
-If running a local instance of MongoDB outside of a docker container that you want your backend to communicate with, you will need to set up [port forwarding in your docker config](https://docs.docker.com/desktop/networking/#use-cases-and-workarounds). Since the intention of this generator is to work with scalable production environments very quickly, providing a local container of MongoDB was not part of the initial charter in its creation. **We do strongly advise you connect to an Atlas cluster** 
+Since the intention of this generator is to work with scalable production environments very quickly, we provide a container of MongoDB, but **We do strongly advise you connect to an Atlas cluster** 
 
 To see how to use MongoDB with Docker, read through this article on [set-up steps](https://www.mongodb.com/compatibility/docker)
 
+
 ### General workflow
 
 By default, the dependencies are managed with [Hatch](https://hatch.pypa.io/latest/), go there and install it.
@@ -782,7 +783,7 @@ This project was generated using https://github.com/tiangolo/full-stack-fastapi-
 
 ```bash
 pip install cookiecutter
-cookiecutter https://github.com/tiangolo/full-stack-fastapi-postgresql
+cookiecutter https://github.com/mongodb-labs/full-stack-fastapi-mongodb.git
 ```
 
 You can check the variables used during generation in the file `cookiecutter-config-file.yml`.

{{cookiecutter.project_slug}}/backend/app/README.md

@@ -1 +1 @@
-__version__ = "0.1.0"
+__version__ = "2023.11.10"

{{cookiecutter.project_slug}}/backend/app/app/__version__.py

@@ -1,5 +1,9 @@
 from app.core.config import settings
+from app.__version__ import __version__
 from motor import motor_asyncio, core
+from pymongo.driver_info import DriverInfo
+
+DRIVER_INFO=DriverInfo(name="full-stack-fastapi-mongodb", version=__version__)
 
 
 class _MongoClientSingleton:
@@ -9,7 +13,8 @@ def __new__(cls):
         if not hasattr(cls, "instance"):
             cls.instance = super(_MongoClientSingleton, cls).__new__(cls)
             cls.instance.mongo_client = motor_asyncio.AsyncIOMotorClient(
-                settings.MONGO_DATABASE_URI
+                settings.MONGO_DATABASE_URI,
+                driver=DRIVER_INFO
             )
         return cls.instance
 

{{cookiecutter.project_slug}}/backend/app/app/db/session.py

@@ -26,6 +26,7 @@ async def app_init(app: FastAPI):
 if settings.BACKEND_CORS_ORIGINS:
     app.add_middleware(
         CORSMiddleware,
+        # Trailing slash causes CORS failures from these supported domains
         allow_origins=[str(origin).rstrip("/") for origin in settings.BACKEND_CORS_ORIGINS],
         allow_credentials=True,
         allow_methods=["*"],

{{cookiecutter.project_slug}}/backend/app/app/main.py

@@ -68,7 +68,7 @@ Copy the contents and use that as password / secret key. And run that again to g
 
 ### Input variables
 
-The generator (cookiecutter) will ask you for some data, you might want to have at hand before generating the project.
+The generator (cookiecutter) will ask you for some data, **you might want to have at hand before generating the project.**
 
 The input variables, with their default values (some auto generated) are:
 
@@ -85,7 +85,7 @@ The input variables, with their default values (some auto generated) are:
 - `secret_key`: Backend server secret key. Use the method above to generate it.
 - `first_superuser`: The first superuser generated, with it you will be able to create more users, etc. By default, based on the domain.
 - `first_superuser_password`: First superuser password. Use the method above to generate it.
-- `backend_cors_origins`: Origins (domains, more or less) that are enabled for CORS (Cross Origin Resource Sharing). This allows a frontend in one domain (e.g. `https://dashboard.example.com`) to communicate with this backend, that could be living in another domain (e.g. `https://api.example.com`). It can also be used to allow your local frontend (with a custom `hosts` domain mapping, as described in the project's `README.md`) that could be living in `http://dev.example.com:8080` to communicate with the backend at `https://stag.example.com`. Notice the `http` vs `https` and the `dev.` prefix for local development vs the "staging" `stag.` prefix. By default, it includes origins for production, staging and development, with ports commonly used during local development by several popular frontend frameworks (Vue with `:8080`, React, Angular).
+- `backend_cors_origins`: Origins (domains, more or less) that are enabled for CORS ([Cross Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)). This informs a frontend browser in one domain (e.g. `https://dashboard.example.com`) it can trust this backend, that could be living in another domain (e.g. `https://api.example.com`). It can also be used to allow your local frontend (with a custom `hosts` domain mapping, as described in the project's `README.md`) that could be living in `http://dev.example.com:8080` to communicate with the backend at `https://stag.example.com`. Notice the `http` vs `https` and the `dev.` prefix for local development vs the "staging" `stag.` prefix. By default, it includes origins for production, staging and development, with ports commonly used during local development by several popular frontend frameworks (Vue with `:8080`, React, Angular).
 - `smtp_port`: Port to use to send emails via SMTP. By default `587`.
 - `smtp_host`: Host to use to send emails, it would be given by your email provider, like Mailgun, Sparkpost, etc.
 - `smtp_user`: The user to use in the SMTP connection. The value will be given by your email provider.