mirror of
https://github.com/fastapi/full-stack-fastapi-template.git
synced 2026-09-21 13:28:57 +00:00
139 lines
4.6 KiB
Markdown
139 lines
4.6 KiB
Markdown
# FastAPI Project - Development
|
|
|
|
## Local Development
|
|
|
|
For local development, run PostgreSQL and Mailpit with Docker Compose, and run the FastAPI and Vite development servers locally.
|
|
|
|
Start the supporting services:
|
|
|
|
```bash
|
|
docker compose up -d db mailpit
|
|
```
|
|
|
|
Then, from the `backend` directory, install the dependencies and prepare the database:
|
|
|
|
```bash
|
|
uv sync
|
|
uv run bash scripts/prestart.sh
|
|
```
|
|
|
|
Start the FastAPI development server:
|
|
|
|
```bash
|
|
uv run fastapi dev
|
|
```
|
|
|
|
In another terminal, from the project root, install the frontend dependencies and start the Vite development server:
|
|
|
|
```bash
|
|
bun install
|
|
bun run dev
|
|
```
|
|
|
|
Now you can open these URLs:
|
|
|
|
Frontend development server: <http://localhost:5173>
|
|
|
|
Backend API: <http://localhost:8000>
|
|
|
|
Automatic interactive API documentation with Swagger UI: <http://localhost:8000/docs>
|
|
|
|
Mailpit: <http://localhost:8025>
|
|
|
|
The frontend development server uses the backend at `http://localhost:8000`, as configured in `frontend/.env`.
|
|
|
|
### Frontend Served by FastAPI
|
|
|
|
Build the frontend from the `frontend` directory:
|
|
|
|
```bash
|
|
bun run build
|
|
```
|
|
|
|
The build is written to `backend/app/frontend` and served by FastAPI at <http://localhost:8000>. Rebuild the frontend after making frontend changes.
|
|
|
|
## Full Stack with Docker Compose
|
|
|
|
To run the backend and built frontend in Docker Compose:
|
|
|
|
```bash
|
|
docker compose run --rm backend bash scripts/prestart.sh
|
|
docker compose watch
|
|
```
|
|
|
|
Now you can open these URLs:
|
|
|
|
Application, with the frontend and API served by FastAPI: <http://localhost:8000>
|
|
|
|
Automatic interactive API documentation with Swagger UI: <http://localhost:8000/docs>
|
|
|
|
Adminer, database web administration: <http://localhost:8080>
|
|
|
|
Traefik UI, to see how the routes are being handled by the proxy: <http://localhost:8090>
|
|
|
|
Mailpit: <http://localhost:8025>
|
|
|
|
Stop a locally running FastAPI server before starting the Compose backend because both use port `8000`.
|
|
|
|
**Note**: The first time you start the stack, it might take a minute for all the services to be ready. To monitor it, use `docker compose logs`, or `docker compose logs backend` for the backend service.
|
|
|
|
## Mailpit
|
|
|
|
[Mailpit](https://mailpit.axllent.org) captures emails sent during local development instead of delivering them. The local backend connects to it at `localhost:1025`, and the Compose backend connects to the `mailpit` service. Captured emails are available at <http://localhost:8025>.
|
|
|
|
## Docker Compose Files and Environment Variables
|
|
|
|
The main `compose.yml` file contains the configuration shared by the whole stack. Docker Compose loads it automatically.
|
|
|
|
The `compose.override.yml` file adds local development settings, such as mounting the source code as a volume. Docker Compose also loads it automatically and applies it on top of `compose.yml`.
|
|
|
|
The `compose.deploy.yml` file contains the deployment-specific settings, including HTTPS and automatic certificate handling. It is explicitly combined with `compose.yml` when deploying the application.
|
|
|
|
The backend reads local settings from the `.env` file. Docker Compose also uses it for variable interpolation and passes the settings each container needs.
|
|
|
|
After changing variables, make sure you restart the stack:
|
|
|
|
```bash
|
|
docker compose watch
|
|
```
|
|
|
|
## The `.env` File
|
|
|
|
The tracked `.env` file contains local development defaults, passwords, and other configuration. Its hostnames use `localhost` for processes running on your machine. Docker Compose overrides hostnames such as the database and SMTP server with their Compose service names.
|
|
|
|
Do not store deployment secrets in `.env`. Configure them as described in the [FastAPI Cloud deployment guide](./deployment.md) or the [Docker Compose deployment guide](./deployment-docker-compose.md).
|
|
|
|
## Pre-commit Hooks and Code Linting
|
|
|
|
The project uses [prek](https://prek.j178.dev/), a modern alternative to [pre-commit](https://pre-commit.com/), for code linting and formatting.
|
|
|
|
You can find a file `.pre-commit-config.yaml` with configurations at the root of the project.
|
|
|
|
### Install `prek` to Run Automatically
|
|
|
|
`prek` is already part of the dependencies of the project.
|
|
|
|
From the project root, install the Git hook so that `prek` runs automatically before each commit:
|
|
|
|
```bash
|
|
uv run prek install -f
|
|
```
|
|
|
|
The `-f` flag forces the installation, in case there was already a `pre-commit` hook previously installed.
|
|
|
|
Now whenever you try to commit, for example with:
|
|
|
|
```bash
|
|
git commit
|
|
```
|
|
|
|
`prek` will check and format the code you are about to commit. If it modifies any files, add those files to Git again before committing.
|
|
|
|
### Run `prek` Manually
|
|
|
|
You can also run `prek` manually on all files from the project root:
|
|
|
|
```bash
|
|
uv run prek run --all-files
|
|
```
|