PYTHON-4095, PYTHON-4096, PYTHON-4098: Rewrite READMEs to be more approachable for first-time users (#12)

Author: Jibola

Diff for: README.md

@@ -6,11 +6,16 @@ This project is for developers looking to build and maintain full-feature progre
 
 This is an **experimental** fork of [Sebastián Ramírez's](https://github.com/tiangolo) [Full Stack FastAPI and PostgreSQL Base Project Generator](https://github.com/tiangolo/full-stack-fastapi-postgresql) and [Whythawk's](https://github.com/whythawk) [Full Stack FastAPI and PostgreSQL Base Project Generator](https://github.com/whythawk/full-stack-fastapi-postgresql). FastAPI is updated to version 0.103.2, MongoDB Motor 3.4, ODMantic ODM 1.0.0, and the frontend to React.
 
+![Landing page](img/landing.png)
+
+## Index
 
+- [Requirements](#requirements)
+- [QuickStart](#quickstart)
 - [Screenshots](#screenshots)
 - [Key features](#key-features)
 - [How to use it](#how-to-use-it)
-  - [Getting started](./docs/getting-started.md)
+  - [Building a generated app](./docs/getting-started.md)
   - [Development and installation](./docs/development-guide.md)
   - [Deployment for production](./docs/deployment-guide.md)
   - [Authentication and magic tokens](./docs/authentication-guide.md)
@@ -19,28 +24,55 @@ This is an **experimental** fork of [Sebastián Ramírez's](https://github.com/t
 - [Help needed](#help-needed)
 - [Release notes](#release-notes)
 - [License](#license)
-  
-## Screenshots
 
-### App landing page
 
-![Landing page](img/landing.png)
+## Requirements
+
+Please make sure you have these installed before proceeding!
+* [Docker Desktop](https://www.docker.com/products/docker-desktop/)
+* [Python 3.11+](https://www.python.org/downloads/)
+* [Cookiecutter](https://cookiecutter.readthedocs.io/en/stable/) -- The Python Cookiecutter library.
+* [Hatch](https://hatch.pypa.io/latest/)
+* [Node.js](https://nodejs.org/en)
+* [MongoDB Compass](https://www.mongodb.com/products/tools/compass) -- To help visualize local/remote database easily.
+
+## QuickStart
+
+**NOTE: this will generate a local application that is not yet production-ready. Please go through all of the README information linked before creating a version to deploy to a production host**
 
-### Dashboard Login
+For those that want to dive in and play around with the generated code, here's a quick start guide on how to do it. It is advised, though, once you have run through generating this app the first time, that you circle back and check out the more fleshed out [Building a generated app](./docs/getting-started.md) section. 
 
-![Magic-link login](img/login.png)
+```
+// Make sure cookiecutter and python are installed on the device
+// This will generate a full-stack app in the directory ./example
+cookiecutter https://github.com/mongodb-labs/full-stack-fastapi-mongodb --no-input project_name="example"
 
-### Dashboard User Management
+// Move into that directory.
+cd example
 
-![Moderator user management](img/dashboard.png)
+// Make sure that you've opened the Docker Desktop app before this step.
+// build
+docker compose build --no-cache
 
-### Interactive API documentation
+// start the container in the background
+docker compose up -d 
+```
 
-![Interactive API docs](img/redoc.png)
+Now you can view the site by going to `localhost:3000`. You can also see all the logs of the running containers in your Docker Desktop app.
 
-### Enabling two-factor security (TOTP)
+There will only be one user on the site: `[email protected]`. If you choose a different project name, then the email domain changes.  For example, if you create your project using`project_name=fullstackexample` the user email will be `[email protected]`. The default password will be set to `changethis` but that can be changed. 
+
+Here are all the local development URLS:
+
+- Frontend -- http://localhost:3000
+- Backend -- http://localhost/api/v1/
+- Automatic Documentation via Swagger UI -- http://localhost/docs
+- Alternative Documentation via ReDoc -- http://localhost/redoc
+- Flower: Admin tool of Celery Tasks -- http://localhost:5555
+- Traefik UI to see how routes are being handled by the proxy: http://localhost:8090
+
+See [Building a generated app](./docs/getting-started.md) for examples of what these pages look like.
 
-![Enabling TOTP](img/totp.png)
 
 ## Key features
 
@@ -55,8 +87,8 @@ This FastAPI, React, MongoDB repo will generate a complete web application stack
   - **Standards-based**: Based on (and fully compatible with) the open standards for APIs: [OpenAPI](https://github.com/OAI/OpenAPI-Specification) and [JSON Schema](http://json-schema.org/).
   - [**Many other features**]("https://fastapi.tiangolo.com/features/"): including automatic validation, serialization, interactive documentation, etc.
 - [**Nextjs/React**](https://nextjs.org/) frontend:
-  - **Authorisation** via middleware for page access, including logged in or superuser.
-  - **Form validation** with [Vee-Validate 4](https://vee-validate.logaretm.com/v4/).
+  - **Authorization** route-based authentication, including support for detecting if a user is logged in or is a superuser.
+  - **Form validation** with [React useForm](https://react-hook-form.com/docs/useform)
   - **State management** with [Redux](https://redux.js.org/)
   - **CSS and templates** with [TailwindCSS](https://tailwindcss.com/), [HeroIcons](https://heroicons.com/), and [HeadlessUI](https://headlessui.com/).
 - **Celery** worker that can import and use models and code from the rest of the backend selectively.
@@ -65,9 +97,9 @@ This FastAPI, React, MongoDB repo will generate a complete web application stack
 - Traefik integration, including Let's Encrypt **HTTPS** certificates automatic generation.
 - GitLab **CI** (continuous integration), including frontend and backend testing.
 
-## How to use it
+## How to use the template
 
-- [Getting started](./docs/getting-started.md)
+- [Building a generated app](./docs/getting-started.md)
 - [Development and installation](./docs/development-guide.md)
 - [Deployment for production](./docs/deployment-guide.md)
 - [Authentication and magic tokens](./docs/authentication-guide.md)
@@ -77,21 +109,34 @@ This FastAPI, React, MongoDB repo will generate a complete web application stack
 
 After using this generator, your new project (the directory created) will contain an extensive `README.md` with instructions for development, deployment, etc. You can pre-read [the project `README.md` template here too](./{{cookiecutter.project_slug}}/README.md).
 
-This current release (October 2023) is for FastAPI version 0.103 and introduces support for Pydantic 2. Since this is intended as a base stack on which you will build complex applications, there is no intention of backwards compatability between releases, and the objective is to ensure that each release has the latest long-term-support versions of the core libraries so that you can rely on your application core for as long as possible.
+This current release is for FastAPI version 0.103 and introduces support for Pydantic 2. Since this is intended as a base stack on which you will build complex applications, there is no intention of backwards compatability between releases, and the objective is to ensure that each release has the latest long-term-support versions of the core libraries so that you can rely on your application core for as long as possible.
 
 To align with [Inboard](https://inboard.bws.bio/), Poetry has been deprecated in favour of [Hatch](https://hatch.pypa.io/latest/). This will also, hopefully, sort out some Poetry-related Docker build errors.
 
 ## Help needed
 
-This stack is in an experimental state, so there is no guarantee for bugs or issues. Please open an issue ticket against this repository to make us aware of issues and we will do our best to respond to them in a timely manner. Please leave feedback on features that would be very beneficial for developers who often leverage mongodb in their FastAPI stack.
+This project is currently experimental, so bugs or issues may occur. Please open an issue ticket against this repository to make us aware of issues and we will do our best to respond to them in a timely manner. Please leave feedback on features that would be very beneficial for developers who often leverage MongoDB in their FastAPI stack.
 
 
 ## Release Notes
 
+**NOTE: There is no intention to have backwards compatibility between releases.**
+
 See notes: 
 
-## CalVer 2023.12.XX
+## CalVer 2024.01.XX
 - Replaced Beanie usage with ODMantic
+- Fixed TOTP login
+- Added Page-Level route authentication
+- Fixed issued with logged in user being unable to access `/settings` page
+- Throw errors on every non-ok auth.ts response
+- Fixed Poject Named generation in Footer.tsx
+- Removed unused CORS routes
+- Updated README
+  - Added QuickStart
+  - Added Requirements
+  - Added Container URL Information
+
 
 ## CalVer 2023.11.10
 

Diff for: docs/authentication-guide.md

@@ -1,9 +1,8 @@
 # Authentication with Magic and Oauth2
 
-1. [Getting started](getting-started.md)
+1. [Building a generated app](getting-started.md)
 2. [Development and installation](development-guide.md)
 3. [Deployment for production](deployment-guide.md)
-4. [Authentication and magic tokens](authentication-guide.md)
 5. [Websockets for interactive communication](websocket-guide.md)
 
 ---

Diff for: docs/getting-started.md

@@ -1,10 +1,12 @@
-# Getting started with the Base Project Generator
+# Building an App with the Base Project Generator
 
-1. [Getting started](getting-started.md)
-2. [Development and installation](development-guide.md)
-3. [Deployment for production](deployment-guide.md)
-4. [Authentication and magic tokens](authentication-guide.md)
-5. [Websockets for interactive communication](websocket-guide.md)
+This page will walk you through the fundamentals of how this app generator works as well as where to look for further details. To learn more about making a production-ready generated application, please read the below sections.
+
+1. [Development and installation](development-guide.md)
+2. [Deployment for production](deployment-guide.md)
+3. [Authentication and magic tokens](authentication-guide.md)
+4. [Websockets for interactive communication](websocket-guide.md)
+5. [Generated project `README.md` template](../{{cookiecutter.project_slug}}/README.md)
 
 ---
 
@@ -30,9 +32,9 @@ This FastAPI, React, MongoDB repo will generate a complete web application stack
   - **Standards-based**: Based on (and fully compatible with) the open standards for APIs: [OpenAPI](https://github.com/OAI/OpenAPI-Specification) and [JSON Schema](http://json-schema.org/).
   - [**Many other features**]("https://fastapi.tiangolo.com/features/"): including automatic validation, serialization, interactive documentation, etc.
 - [**Nextjs/React**](https://nextjs.org/) frontend:
-  - **Authorisation** via middleware for page access, including logged in or superuser.
+  - **Authorization** route-based authentication, including support for detecting if a user is logged in or is a superuser.
   - **Model blog** project, with [Nuxt Content](https://content.nuxtjs.org/) for writing Markdown pages.
-  - **Form validation** with [Vee-Validate 4](https://vee-validate.logaretm.com/v4/).
+  - **Form validation** with [React useForm](https://react-hook-form.com/docs/useform)
   - **State management** with [Redux](https://redux.js.org/)
   - **CSS and templates** with [TailwindCSS](https://tailwindcss.com/), [HeroIcons](https://heroicons.com/), and [HeadlessUI](https://headlessui.com/).
 - **Celery** worker that can import and use models and code from the rest of the backend selectively.
@@ -42,7 +44,6 @@ This FastAPI, React, MongoDB repo will generate a complete web application stack
 - **Github Actions** (continuous integration), including backend testing.
 
 
-
 ## 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, leveraging a NoSQL Datastore (MongoDB). The base deployment requires about 2Gb of memory to run. 
@@ -102,12 +103,3 @@ Time-based One-Time Password (TOTP) authentication extends the login process to
 ### More details
 
 After using this generator, your new project will contain an extensive `README.md` with instructions for development, deployment, etc. You can pre-read [the project `README.md` template here too](../{{cookiecutter.project_slug}}/README.md).
-
-## Release Notes
-
-### 2023.11.10
-- Experimental release of FARM-stack generator app
-
-## License
-
-This project is licensed under the terms of the MIT license.

Diff for: docs/websocket-guide.md

@@ -18,7 +18,7 @@ While Websockets support multi-user sessions, this documentation is mainly focus
 - [Why Websockets?](#why-websockets)
 - [High-level architecture and workflow](#high-level-architecture-and-workflow)
 - [Requirements](#requirements)
-- [Setting up the Nuxt `frontend`](#setting-up-the-nuxt-frontend)
+- [Setting up the React `frontend`](#setting-up-the-react-frontend)
 - [Setting up the FastAPI `backend`](#setting-up-the-fastapi-backend)
 
 ## Why Websockets?

Diff for: {{cookiecutter.project_slug}}/README.md

@@ -80,7 +80,7 @@ Next, open your editor at `./backend/app/` (instead of the project root: `./`),
 $ code .
 ```
 
-Modify or add beanie models in `./backend/app/app/models/` (make sure to include them in `MODELS` within `.backend/app/app/models/__init__.py`), Pydantic schemas in `./backend/app/app/schemas/`, API endpoints in `./backend/app/app/api/`, CRUD (Create, Read, Update, Delete) utils in `./backend/app/app/crud/`. The easiest might be to copy the ones for Items (models, endpoints, and CRUD utils) and update them to your needs.
+Modify or add ODMantic models in `./backend/app/app/models/`, Pydantic schemas in `./backend/app/app/schemas/`, API endpoints in `./backend/app/app/api/`, CRUD (Create, Read, Update, Delete) utils in `./backend/app/app/crud/`. The easiest might be to copy the ones for Items (models, endpoints, and CRUD utils) and update them to your needs.
 
 Add and modify tasks to the Celery worker in `./backend/app/app/worker.py`.
 
@@ -223,48 +223,6 @@ http://localhost:8888/token=f20939a41524d021fbfc62b31be8ea4dd9232913476f4397
 
 You will have a full Jupyter Notebook running inside your container that has direct access to your database by the container name (`db`), etc. So, you can just run sections of your backend code directly, for example with [VS Code Python Jupyter Interactive Window](https://code.visualstudio.com/docs/python/jupyter-support-py) or [Hydrogen](https://github.com/nteract/hydrogen).
 
-### Migrations
-
-As during local development your app directory is mounted as a volume inside the container, you can also run the migrations with `alembic` commands inside the container and the migration code will be in your app directory (instead of being only inside the container). So you can add it to your git repository.
-
-Make sure you create a "revision" of your models and that you "upgrade" your database with that revision every time you change them. As this is what will update the tables in your database. Otherwise, your application will have errors.
-
-* Start an interactive session in the backend container:
-
-```console
-$ docker-compose exec backend bash
-```
-
-* If you created a new model in `./backend/app/app/models/`, make sure to import it in `./backend/app/app/db/base.py`, that Python module (`base.py`) that imports all the models will be used by Alembic.
-
-* After changing a model (for example, adding a column), inside the container, create a revision, e.g.:
-
-```console
-$ alembic revision --autogenerate -m "Add column last_name to User model"
-```
-
-* Commit to the git repository the files generated in the alembic directory.
-
-* After creating the revision, run the migration in the database (this is what will actually change the database):
-
-```console
-$ alembic upgrade head
-```
-
-If you don't want to use migrations at all, uncomment the line in the file at `./backend/app/app/db/init_db.py` with:
-
-```python
-Base.metadata.create_all(bind=engine)
-```
-
-and comment the line in the file `prestart.sh` that contains:
-
-```console
-$ alembic upgrade head
-```
-
-If you don't want to start with the default models and want to remove them / modify them, from the beginning, without having any previous revision, you can remove the revision files (`.py` Python files) under `./backend/app/alembic/versions/`. And then create a first migration as described above.
-
 ### Development with Docker Toolbox
 
 If you are using **Docker Toolbox** in Windows or macOS instead of **Docker for Windows** or **Docker for Mac**, Docker will be running in a VirtualBox Virtual Machine, and it will have a local IP different than `127.0.0.1`, which is the IP address for `localhost` in your machine.
@@ -701,7 +659,7 @@ Flower: https://flower.{{cookiecutter.domain_staging}}
 
 Development URLs, for local development.
 
-Frontend: http://localhost
+Frontend: http://localhost:3000
 
 Backend: http://localhost/api/