For local development, run PostgreSQL and Mailcatcher with Docker Compose, and run the FastAPI and Vite development servers locally.

Start the supporting services:

docker compose up -d db mailcatcher

Then, from the backend directory, install the dependencies and prepare the database:

uv sync
uv run bash scripts/prestart.sh

Start the FastAPI development server:

uv run fastapi dev

In another terminal, from the project root, install the frontend dependencies and start the Vite development server:

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

Mailcatcher: http://localhost:1080

The frontend development server uses the backend at http://localhost:8000, as configured in frontend/.env.

Build the frontend from the frontend directory:

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.

To run the backend and built frontend in Docker Compose:

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

Mailcatcher: http://localhost:1080

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.

Mailcatcher 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 mailcatcher service. Captured emails are available at http://localhost:1080.

There is a main compose.yml file with all the configurations that apply to the whole stack, it is used automatically by docker compose.

And there's also a compose.override.yml with overrides for development, for example to mount the source code as a volume. It is used automatically by docker compose to apply overrides 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:

docker compose watch

The .env file contains the shared local defaults, generated keys, 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.

Depending on your workflow, you could want to exclude it from Git, for example if your project is public. In that case, you would have to make sure to set up a way for your CI tools to obtain it while building or deploying your project.

One way to do it could be to add each environment variable to your CI/CD system.

we are using a tool called prek (modern alternative to Pre-commit) for code linting and formatting.

When you install it, it runs right before making a commit in git. This way it ensures that the code is consistent and formatted even before it is committed.

You can find a file .pre-commit-config.yaml with configurations at the root of the project.

prek is already part of the dependencies of the project.

After having the prek tool installed and available, you need to "install" it in the local repository, so that it runs automatically before each commit.

Using uv, you could do it with (make sure you are inside backend folder):

❯ uv run prek install -f
prek installed at `../.git/hooks/pre-commit`

The -f flag forces the installation, in case there was already a pre-commit hook previously installed.

Now whenever you try to commit, e.g. with:

git commit

...prek will run and check and format the code you are about to commit, and will ask you to add that code (stage it) with git again before committing.

Then you can git add the modified/fixed files again and now you can commit.

you can also run prek manually on all the files, you can do it using uv with:

❯ uv run prek run --all-files
check for added large files..............................................Passed
check toml...............................................................Passed
check yaml...............................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff.....................................................................Passed
ruff-format..............................................................Passed
biome check..............................................................Passed

The deployed URLs use these same paths, but with your own domain.

Development URLs, for local development.

Application: http://localhost:8000

Automatic Interactive Docs (Swagger UI): http://localhost:8000/docs

Automatic Alternative Docs (ReDoc): http://localhost:8000/redoc

Adminer: http://localhost:8080

Traefik UI: http://localhost:8090

MailCatcher: http://localhost:1080