full-stack-fastapi-template/backend/README.md

FastAPI Project - Backend

Requirements

• Docker.
• uv for Python package and environment management.

Local Development

Run the backend locally and connect it to PostgreSQL in Docker Compose.

From the project root, start PostgreSQL and Mailcatcher:

$ docker compose up -d db mailcatcher

Then, from ./backend/, install the dependencies, prepare the database, and start the development server:

$ uv sync
$ uv run bash scripts/prestart.sh
$ uv run fastapi dev

The API is available at http://localhost:8000, with automatic interactive docs at http://localhost:8000/docs.

General Workflow

By default, the dependencies are managed with uv, go there and install it.

From ./backend/ you can install all the dependencies with:

$ uv sync

Then you can activate the virtual environment with:

$ source .venv/bin/activate

Make sure your editor is using the correct Python virtual environment, with the interpreter at backend/.venv/bin/python.

Modify or add SQLModel models for data and SQL tables in ./backend/app/models.py, API endpoints in ./backend/app/api/, CRUD (Create, Read, Update, Delete) utils in ./backend/app/crud.py.

VS Code

There are already configurations in place to run the backend through the VS Code debugger, so that you can use breakpoints, pause and explore variables, etc.

The setup is also already configured so you can run the tests through the VS Code Python tests tab.

Full Stack with Docker Compose

To run the backend and built frontend in Docker Compose:

$ docker compose watch

The application is available at http://localhost:8000.

Docker Compose Override

The compose.override.yml file contains local settings for published ports, source synchronization, automatic image rebuilds, and backend reloads. Docker Compose applies it automatically when you run docker compose without an explicit file list.

To open a shell in the backend container:

$ docker compose exec backend bash

Backend tests

To test the backend from the backend directory, run:

$ uv run bash ./scripts/test.sh

The tests run with Pytest, modify and add tests to ./backend/tests/.

If you use GitHub Actions the tests will run automatically.

Test running stack

If your stack is already up and you just want to run the tests, you can use:

docker compose exec backend bash scripts/tests-start.sh

That /app/scripts/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:

docker compose exec backend bash scripts/tests-start.sh -x

Test Coverage

When the tests are run, a file htmlcov/index.html is generated, you can open it in your browser to see the coverage of the tests.

Migrations

Make sure you create a revision of your models and upgrade the database with that revision every time you change them. From the backend directory, use uv to run Alembic against the PostgreSQL container:

• Alembic is already configured to import your SQLModel models from ./backend/app/models.py.

• After changing a model (for example, adding a column), create a revision:

$ uv run 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):

$ uv run alembic upgrade head

If you don't want to use migrations at all, uncomment the lines in the file at ./backend/app/core/db.py that end in:

SQLModel.metadata.create_all(engine)

and comment the line in the file scripts/prestart.sh that contains:

$ 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.

Email Templates

The email templates are in ./backend/app/email-templates/. Here, there are two directories: build and src. The src directory contains the source files that are used to build the final email templates. The build directory contains the final email templates that are used by the application.

Before continuing, ensure you have the MJML extension installed in your VS Code.

Once you have the MJML extension installed, you can create a new email template in the src directory. After creating the new email template and with the .mjml file open in your editor, open the command palette with Ctrl+Shift+P and search for MJML: Export to HTML. This will convert the .mjml file to a .html file and now you can save it in the build directory.