Version updates & refactoring across the stack

Updates to `backend`: - FastAPI 0.99 -> 0.109 (Inboard 0.51 -> 0.68) - Pydantic 1.10 -> 2.7.1 Updates to `frontend`: - NuxtJS 3.6.5 -> 3.11.2 - Nuxtjs i18n 8.0.0 RC -> 8.3.1 The Pydantic change is dramatic, so please revise their [migration guide](https://docs.pydantic.dev/2.7/migration/). Similarly, [nuxt/i18n](https://i18n.nuxtjs.org/docs/getting-started) has some major quality of life improvements. This update necessitated refactoring across the stack.
whythawk · May 2, 2024 · 9f9b025 · 9f9b025
1 parent a76587d
commit 9f9b025
Show file tree

Hide file tree

Showing 72 changed files with 5,783 additions and 4,274 deletions.
diff --git a/README.md b/README.md
@@ -2,76 +2,75 @@
 
 [![Build Status](https://app.travis-ci.com/whythawk/full-stack-fastapi-postgresql.svg?branch=master)](https://app.travis-ci.com/whythawk/full-stack-fastapi-postgresql)
 
-Accelerate your next web development project with this FastAPI/Nuxt.js base project generator.
+Accelerate your next web development project with this FastAPI/NuxtJS base project generator.
 
 This project is for developers looking to build and maintain full-feature progressive web applications using Python on the backend / Typescript on the frontend, and want the complex-but-routine aspects of auth 'n auth, and component and deployment configuration, taken care of, including interactive API documentation. 
 
-This is a comprehensively updated 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). FastAPI is updated to version 0.99 (July 2023), SQLAlchemy to version 2.0 (July 2023), and the frontend to Nuxt 3.6 (July 2023).
+This project is a 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). FastAPI is updated to version 0.109 (April 2024), SQLAlchemy to version 2.0.29 (March 2024), and the frontend to Nuxt 3.11 (April 2024).
 
-- [Screenshots](#screenshots)
 - [Key features](#key-features)
+- [Screenshots](#screenshots)
 - [How to use it](#how-to-use-it)
   - [Getting started](./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)
   - [Websockets for interactive communication](./docs/websocket-guide.md)
+- [Fork differences](#fork-differences)
 - [More details](#more-details)
 - [Help needed](#help-needed)
 - [Release notes](#release-notes)
 - [License](#license)
 
-## Screenshots
-
-### App landing page
-
-![Landing page](img/landing.png)
-
-### Dashboard Login
-
-![Magic-link login](img/login.png)
-
-### Dashboard User Management
-
-![Moderator user management](img/dashboard.png)
-
-### Interactive API documentation
-
-![Interactive API docs](img/redoc.png)
-
-### Enabling two-factor security (TOTP)
-
-![Enabling TOTP](img/totp.png)
-
 ## Key features
 
 This FastAPI, PostgreSQL, Neo4j & Nuxt 3 repo will generate a complete web application stack as a foundation for your project development.
 
 - **Docker Compose** integration and optimization for local development.
 - **Authentication** user management schemas, models, crud and apis already built, with OAuth2 JWT token support & default hashing. Offers _magic link_ authentication, with password fallback, with cookie management, including `access` and `refresh` tokens.
-- [**FastAPI**](https://github.com/tiangolo/fastapi) backend with [Inboard](https://inboard.bws.bio/) one-repo Docker images:
+- [**FastAPI**](https://github.com/tiangolo/fastapi) backend with [Inboard](https://inboard.bws.bio/) one-repo Docker images, using Python 3.11:
   - **SQLAlchemy** version 2.0 support for models.
-  - **MJML** templates for common email transactions.
+  - **Pydantic** version 2.7 for schemas.
   - **Metadata Schema** based on [Dublin Core](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/#section-3) for inheritance.
   - **Common CRUD** support via generic inheritance.
   - **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/).
+  - **MJML** templates for common email transactions.
   - [**Many other features**]("https://fastapi.tiangolo.com/features/"): including automatic validation, serialization, interactive documentation, etc.
-- [**Nuxt/Vue 3**](https://nuxt.com/) frontend:
+- [**Nuxt/Vue 3**](https://nuxt.com/) frontend using TypeScript:
   - **Authorisation** via middleware for page access, including logged in or 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/).
   - **State management** with [Pinia](https://pinia.vuejs.org/), and persistance with [Pinia PersistedState](https://prazdevs.github.io/pinia-plugin-persistedstate/).
   - **CSS and templates** with [TailwindCSS](https://tailwindcss.com/), [HeroIcons](https://heroicons.com/), and [HeadlessUI](https://headlessui.com/).
-  - **Internationalisation** with [@nuxt/i18n](https://nuxt.com/modules/i18n).
-  - **PWA support** with [Vite PWA plugin](https://vite-pwa-org.netlify.app/frameworks/nuxt.html).
 - **PostgreSQL** database.
 - **PGAdmin** for PostgreSQL database management.
 - **Celery** worker that can import and use models and code from the rest of the backend selectively.
 - **Flower** for Celery jobs monitoring.
 - **Neo4j** graph database, including integration into the FastAPI base project.
 - Load balancing between frontend and backend with **Traefik**, so you can have both under the same domain, separated by path, but served by different containers.
 - Traefik integration, including Let's Encrypt **HTTPS** certificates automatic generation.
-- GitLab **CI** (continuous integration), including frontend and backend testing.
+
+## Screenshots
+
+### App landing page
+
+![Landing page](img/landing.png)
+
+### Dashboard Login
+
+![Magic-link login](img/login.png)
+
+### Dashboard User Management
+
+![Moderator user management](img/dashboard.png)
+
+### Interactive API documentation
+
+![Interactive API docs](img/redoc.png)
+
+### Enabling two-factor security (TOTP)
+
+![Enabling TOTP](img/totp.png)
 
 ## How to use it
 
@@ -81,15 +80,32 @@ This FastAPI, PostgreSQL, Neo4j & Nuxt 3 repo will generate a complete web appli
 - [Authentication and magic tokens](./docs/authentication-guide.md)
 - [Websockets for interactive communication](./docs/websocket-guide.md)
 
+## Fork differences
+
+The original objective of this fork was to maintain parity with the [Full Stack FastAPI and PostgreSQL Base Project Generator](https://github.com/tiangolo/full-stack-fastapi-postgresql) but update it to bring it up to current stack versions, fixes, and with a complete auth 'n auth system.
+
+With the most recent updates to the base stack, Sebastián has made some fairly dramatic changes and these two stacks are no longer compatible. This table presents a summary of the major differences:
+
+| This base stack                  | Tiangolo base stack     |
+| :------------------------------- | :---------------------- |
+| SQLAlchemy & Pydantic            | SqlModel                |
+| Postgresql 15 & PGAdmin          | Postgresql 12 & Adminer |
+| Celery & RabbitMQ task queue     | -                       |
+| NuxtJS frontend                  | React frontend          |
+
+I use this stack to produce some fairly complex web-based applications and I need to get to the full APIs for SQLAlchemy and Pydantic, and SqlModel doesn't offer me that. I also need to run distributed asyncronous tasks, so Celery is important. Finally, I prefer Nuxt.
+
+This stack also has a much more sophisticated and feature-complete auth 'n auth system which is a requirement for any web app.
+
 ## More details
 
 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 (August 2023) is for FastAPI version 0.99 and is the last before introducing 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 (May 2024) is for FastAPI version 0.109 introduces support for Pydantic 2.7. 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.
+To align with [Inboard](https://inboard.bws.bio/), Poetry has been deprecated in favour of [Hatch](https://hatch.pypa.io/latest/).
 
-You will also find an initial implementation of internationalisation using [@nuxt/i18n](https://nuxt.com/modules/i18n). This is - at this time - a release candidate, so please do update and check their documentation for any changes. The [Vite PWA plugin](https://vite-pwa-org.netlify.app/frameworks/nuxt.html) is also included, along with a Node CLI for generating all necessary app icons. You will see links and notes to this in the [nuxt.config.ts](./{{cookiecutter.project_slug}}/frontend/nuxt.config.ts) file.
+You will also find an initial implementation of internationalisation using [@nuxt/i18n](https://nuxt.com/modules/i18n). The [Vite PWA plugin](https://vite-pwa-org.netlify.app/frameworks/nuxt.html) is also included, along with a Node CLI for generating all necessary app icons. You will see links and notes to this in the [nuxt.config.ts](./{{cookiecutter.project_slug}}/frontend/nuxt.config.ts) file.
 
 ## Help needed
 
@@ -103,6 +119,18 @@ The tests are broken and it would be great if someone could take that on. Other
 
 See notes and [releases](https://github.com/whythawk/full-stack-fastapi-postgresql/releases). 
 
+## 0.9.0
+
+Updates to `backend`:
+- FastAPI 0.99 -> 0.109 (Inboard 0.51 -> 0.68)
+- Pydantic 1.10 -> 2.7.1
+
+Updates to `frontend`:
+- NuxtJS 3.6.5 -> 3.11.2
+- Nuxtjs i18n 8.0.0 RC -> 8.3.1
+
+The Pydantic change is dramatic, so please revise their [migration guide](https://docs.pydantic.dev/2.7/migration/). Similarly, [nuxt/i18n](https://i18n.nuxtjs.org/docs/getting-started) has some major quality of life improvements.
+
 ## 0.8.2
 
 Fixing [#39](https://github.com/whythawk/full-stack-fastapi-postgresql/issues/39), thanks to @a-vorobyoff:

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -25,14 +25,15 @@ It consists of the following key components:
 
 - **Docker Compose** integration and optimization for local development.
 - **Authentication** user management schemas, models, crud and apis already built, with OAuth2 JWT token support & default hashing. Offers _magic link_ authentication, with password fallback, with cookie management, including `access` and `refresh` tokens.
-- [**FastAPI**](https://github.com/tiangolo/fastapi) backend with [Inboard](https://inboard.bws.bio/) one-repo Docker images:
+- [**FastAPI**](https://github.com/tiangolo/fastapi) backend with [Inboard](https://inboard.bws.bio/) one-repo Docker images, using Python 3.11:
   - **SQLAlchemy** version 2.0 support for models.
-  - **MJML** templates for common email transactions.
+  - **Pydantic** version 2.7 for schemas.
   - **Metadata Schema** based on [Dublin Core](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/#section-3) for inheritance.
   - **Common CRUD** support via generic inheritance.
   - **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/).
+  - **MJML** templates for common email transactions.
   - [**Many other features**]("https://fastapi.tiangolo.com/features/"): including automatic validation, serialization, interactive documentation, etc.
-- [**Nuxt/Vue 3**](https://nuxt.com/) frontend:
+- [**Nuxt/Vue 3**](https://nuxt.com/) frontend using TypeScript:
   - **Authorisation** via middleware for page access, including logged in or 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/).
@@ -45,7 +46,6 @@ It consists of the following key components:
 - **Neo4j** graph database, including integration into the FastAPI base project.
 - Load balancing between frontend and backend with **Traefik**, so you can have both under the same domain, separated by path, but served by different containers.
 - Traefik integration, including Let's Encrypt **HTTPS** certificates automatic generation.
-- GitLab **CI** (continuous integration), including frontend and backend testing.
 
 ## Who is it for?
 
@@ -105,6 +105,18 @@ After using this generator, your new project will contain an extensive `README.m
 
 See notes and [releases](https://github.com/whythawk/full-stack-fastapi-postgresql/releases). The last four release notes are listed here:
 
+## 0.9.0
+
+Updates to `backend`:
+- FastAPI 0.99 -> 0.109 (Inboard 0.51 -> 0.68)
+- Pydantic 1.10 -> 2.7.1
+
+Updates to `frontend`:
+- NuxtJS 3.6.5 -> 3.11.2
+- Nuxtjs i18n 8.0.0 RC -> 8.3.1
+
+The Pydantic change is dramatic, so please revise their [migration guide](https://docs.pydantic.dev/2.7/migration/). Similarly, [nuxt/i18n](https://i18n.nuxtjs.org/docs/getting-started) has some major quality of life improvements.
+
 ## 0.8.2
 
 Fixing [#39](https://github.com/whythawk/full-stack-fastapi-postgresql/issues/39), thanks to @a-vorobyoff:

diff --git a/img/docs.png b/img/docs.png
diff --git a/{{cookiecutter.project_slug}}/.gitattributes b/{{cookiecutter.project_slug}}/.gitattributes
@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text eol=lf
diff --git a/{{cookiecutter.project_slug}}/README.md b/{{cookiecutter.project_slug}}/README.md
@@ -30,13 +30,13 @@ Traefik UI, to see how the routes are being handled by the proxy: http://localho
 To check the logs, run:
 
 ```bash
-docker-compose logs
+docker compose logs
 ```
 
 To check the logs of a specific service, add the name of the service, e.g.:
 
 ```bash
-docker-compose logs backend
+docker compose logs backend
 ```
 
 If your Docker is not running in `localhost` (the URLs above wouldn't work) check the sections below on **Development with Docker Toolbox** and **Development with a custom IP**.
@@ -81,21 +81,21 @@ The changes to that file only affect the local development environment, not the
 For example, the directory with the backend code is mounted as a Docker "host volume", mapping the code you change live to the directory inside the container. That allows you to test your changes right away, without having to build the Docker image again. It should only be done during development, for production, you should build the Docker image with a recent version of the backend code. But during development, it allows you to iterate very fast. Have in mind that if you have a syntax error and save the Python file, it will break and exit, and the container will stop. After that, you can restart the container by fixing the error and running again:
 
 ```console
-$ docker-compose up -d
+$ docker compose up -d
 ```
 
 There is also a commented out `command` override, you can uncomment it and comment the default one. It makes the backend container run a process that does "nothing", but keeps the container alive. That allows you to get inside your running container and execute commands inside, for example a Python interpreter to test installed dependencies, or start the development server that reloads when it detects changes, or start a Jupyter Notebook session.
 
 To get inside the container with a `bash` session you can start the stack with:
 
 ```console
-$ docker-compose up -d
+$ docker compose up -d
 ```
 
 and then `exec` inside the running container:
 
 ```console
-$ docker-compose exec backend bash
+$ docker compose exec backend bash
 ```
 
 You should see an output like:
@@ -133,23 +133,23 @@ The `./backend/app` directory is mounted as a "host volume" inside the docker co
 You can rerun the test on live code:
 
 ```Bash
-docker-compose exec backend /app/tests-start.sh
+docker compose exec backend /app/tests-start.sh
 ```
 
 #### Test running stack
 
 If your stack is already up and you just want to run the tests, you can use:
 
 ```bash
-docker-compose exec backend /app/tests-start.sh
+docker compose exec backend /app/tests-start.sh
 ```
 
 That `/app/tests-start.sh` script just calls `pytest` after making sure that the rest of the stack is running. If you need to pass extra arguments to `pytest`, you can pass them to that command and they will be forwarded.
 
 For example, to stop on first error:
 
 ```bash
-docker-compose exec backend bash /app/tests-start.sh -x
+docker compose exec backend bash /app/tests-start.sh -x
 ```
 
 #### Test Coverage
@@ -165,7 +165,7 @@ DOMAIN=backend sh ./scripts/test-local.sh --cov-report=html
 To run the tests in a running stack with coverage HTML reports:
 
 ```bash
-docker-compose exec backend bash /app/tests-start.sh --cov-report=html
+docker compose exec backend bash /app/tests-start.sh --cov-report=html
 ```
 
 ### Live development with Python Jupyter Notebooks
@@ -177,7 +177,7 @@ The `docker-compose.override.yml` file sends a variable `env` with a value `dev`
 So, you can enter into the running Docker container:
 
 ```bash
-docker-compose exec backend bash
+docker compose exec backend bash
 ```
 
 And use the environment variable `$JUPYTER` to run a Jupyter Notebook with everything configured to listen on the public port (so that you can use it from your browser).
@@ -218,7 +218,7 @@ Make sure you create a "revision" of your models and that you "upgrade" your dat
 * Start an interactive session in the backend container:
 
 ```console
-$ docker-compose exec backend bash
+$ 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.
@@ -349,7 +349,7 @@ That variable will make your frontend communicate with that domain when interact
 After changing the two lines, you can re-start your stack with:
 
 ```bash
-docker-compose up -d
+docker compose up -d
 ```
 
 and check all the corresponding available URLs in the section at the end.
@@ -587,11 +587,11 @@ TAG=${TAG?Variable not set} \
 # a default value of "production" if nothing else was passed
 FRONTEND_ENV=${FRONTEND_ENV-production?Variable not set} \
 # The actual comand that does the work: docker-compose
-docker-compose \
+docker compose \
 # Pass the file that should be used, setting explicitly docker-compose.yml avoids the
 # default of also using docker-compose.override.yml
 -f docker-compose.yml \
-# Use the docker-compose sub command named "config", it just uses the docker-compose.yml
+# Use the docker compose sub command named "config", it just uses the docker-compose.yml
 # file passed to it and prints their combined contents
 # Put those contents in a file "docker-stack.yml", with ">"
 config > docker-stack.yml

diff --git a/{{cookiecutter.project_slug}}/backend/.dockerignore b/{{cookiecutter.project_slug}}/backend/.dockerignore
@@ -1,3 +1,4 @@
 # Get rid of .venv when copying
+# https://docs.docker.com/engine/reference/builder/#dockerignore-file
 */.venv
 */*/.venv