mirror of
https://github.com/fastapi/full-stack-fastapi-template.git
synced 2026-09-23 06:10:54 +00:00
147 lines
5.1 KiB
Markdown
147 lines
5.1 KiB
Markdown
# FastAPI Project - Backend
|
|
|
|
## Requirements
|
|
|
|
* [Docker](https://www.docker.com/).
|
|
* [uv](https://docs.astral.sh/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:
|
|
|
|
```console
|
|
$ docker compose up -d db mailcatcher
|
|
```
|
|
|
|
Then, from `./backend/`, install the dependencies, prepare the database, and start the development server:
|
|
|
|
```console
|
|
$ 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](https://docs.astral.sh/uv/), go there and install it.
|
|
|
|
From `./backend/` you can install all the dependencies with:
|
|
|
|
```console
|
|
$ uv sync
|
|
```
|
|
|
|
Then you can activate the virtual environment with:
|
|
|
|
```console
|
|
$ 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:
|
|
|
|
```console
|
|
$ 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:
|
|
|
|
```console
|
|
$ docker compose exec backend bash
|
|
```
|
|
|
|
## Backend tests
|
|
|
|
To test the backend from the `backend` directory, run:
|
|
|
|
```console
|
|
$ 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```console
|
|
$ 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):
|
|
|
|
```console
|
|
$ 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:
|
|
|
|
```python
|
|
SQLModel.metadata.create_all(engine)
|
|
```
|
|
|
|
and comment the line in the file `scripts/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.
|
|
|
|
## 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](https://github.com/mjmlio/vscode-mjml) 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.
|