♻️ Replace Mailcatcher with Mailpit for local email testing

2026-11-03 20:36:27 +00:00 · 2026-08-11 21:28:55 +02:00
22 changed files with 420 additions and 409 deletions
@@ -1,6 +1,7 @@
 .git
 **/__pycache__
 **/.venv
 backend/app/frontend
 backend/htmlcov
 frontend/blob-report
 frontend/dist
@@ -1,2 +0,0 @@
 .env
 !backend/app/frontend/
@@ -0,0 +1,25 @@
 docs:
  - all:
    - changed-files:
      - any-glob-to-any-file:
        - '**/*.md'
      - all-globs-to-all-files:
        - '!frontend/**'
        - '!backend/**'
        - '!.github/**'
        - '!scripts/**'
        - '!.gitignore'
        - '!.pre-commit-config.yaml'
 internal:
  - all:
    - changed-files:
      - any-glob-to-any-file:
        - .github/**
        - scripts/**
        - .gitignore
        - .pre-commit-config.yaml
      - all-globs-to-all-files:
        - '!./**/*.md'
        - '!frontend/**'
        - '!backend/**'
@@ -1,12 +0,0 @@
 auto-labels:
  docs:
    - exclude: frontend/**
    - exclude: backend/**
    - exclude: .github/**
    - exclude: scripts/**
    - '**/*.md'
  internal:
    - .github/**
    - scripts/**
    - .gitignore
    - .pre-commit-config.yaml
@@ -1,41 +0,0 @@
 name: Deploy with Docker Compose
 on:
  workflow_dispatch:
 permissions:
  contents: read
 concurrency:
  group: deploy-docker-compose
  cancel-in-progress: false
 jobs:
  deploy:
    # Do not deploy the template repository, only projects created from it
    if: github.repository != 'fastapi/full-stack-fastapi-template'
    runs-on: self-hosted
    timeout-minutes: 30
    env:
      DOMAIN: ${{ vars.DOMAIN }}
      PROJECT_NAME: ${{ vars.PROJECT_NAME }}
      SECRET_KEY: ${{ secrets.SECRET_KEY }}
      FIRST_SUPERUSER: ${{ vars.FIRST_SUPERUSER }}
      FIRST_SUPERUSER_PASSWORD: ${{ secrets.FIRST_SUPERUSER_PASSWORD }}
      SMTP_HOST: ${{ vars.SMTP_HOST }}
      SMTP_USER: ${{ vars.SMTP_USER }}
      SMTP_PASSWORD: ${{ secrets.SMTP_PASSWORD }}
      EMAILS_FROM_EMAIL: ${{ vars.EMAILS_FROM_EMAIL }}
      POSTGRES_PASSWORD: ${{ secrets.POSTGRES_PASSWORD }}
      SENTRY_DSN: ${{ vars.SENTRY_DSN }}
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - name: Build
        run: docker compose -f compose.yml -f compose.deploy.yml build
      - name: Prepare database
        run: docker compose -f compose.yml -f compose.deploy.yml run --rm backend bash scripts/prestart.sh
      - name: Start application
        run: docker compose -f compose.yml -f compose.deploy.yml up -d
@@ -0,0 +1,37 @@
 name: Deploy to Production
 on:
  release:
    types:
      - published
 permissions:
  contents: read
 jobs:
  deploy:
    environment: production
    # Do not deploy in the main repository, only in user projects
    if: github.repository_owner != 'fastapi'
    runs-on:
      - self-hosted
      - production
    env:
      DOMAIN: ${{ secrets.DOMAIN }}
      SECRET_KEY: ${{ secrets.SECRET_KEY }}
      FIRST_SUPERUSER: ${{ secrets.FIRST_SUPERUSER }}
      FIRST_SUPERUSER_PASSWORD: ${{ secrets.FIRST_SUPERUSER_PASSWORD }}
      SMTP_HOST: ${{ secrets.SMTP_HOST }}
      SMTP_USER: ${{ secrets.SMTP_USER }}
      SMTP_PASSWORD: ${{ secrets.SMTP_PASSWORD }}
      EMAILS_FROM_EMAIL: ${{ secrets.EMAILS_FROM_EMAIL }}
      POSTGRES_PASSWORD: ${{ secrets.POSTGRES_PASSWORD }}
      SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - run: docker compose -f compose.yml -f compose.deploy.yml build
      - run: docker compose -f compose.yml -f compose.deploy.yml run --rm backend bash scripts/prestart.sh
      - run: docker compose -f compose.yml -f compose.deploy.yml up -d
@@ -0,0 +1,37 @@
 name: Deploy to Staging
 on:
  push:
    branches:
      - master
 permissions:
  contents: read
 jobs:
  deploy:
    environment: staging
    # Do not deploy in the main repository, only in user projects
    if: github.repository_owner != 'fastapi'
    runs-on:
      - self-hosted
      - staging
    env:
      DOMAIN: ${{ secrets.DOMAIN }}
      SECRET_KEY: ${{ secrets.SECRET_KEY }}
      FIRST_SUPERUSER: ${{ secrets.FIRST_SUPERUSER }}
      FIRST_SUPERUSER_PASSWORD: ${{ secrets.FIRST_SUPERUSER_PASSWORD }}
      SMTP_HOST: ${{ secrets.SMTP_HOST }}
      SMTP_USER: ${{ secrets.SMTP_USER }}
      SMTP_PASSWORD: ${{ secrets.SMTP_PASSWORD }}
      EMAILS_FROM_EMAIL: ${{ secrets.EMAILS_FROM_EMAIL }}
      POSTGRES_PASSWORD: ${{ secrets.POSTGRES_PASSWORD }}
      SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - run: docker compose -f compose.yml -f compose.deploy.yml build
      - run: docker compose -f compose.yml -f compose.deploy.yml run --rm backend bash scripts/prestart.sh
      - run: docker compose -f compose.yml -f compose.deploy.yml up -d
@@ -1,54 +0,0 @@
 name: Deploy
 on:
  push:
    branches:
      - master
    paths-ignore:
      - release-notes.md
  workflow_dispatch:
 permissions:
  contents: read
 jobs:
  deploy:
    # Do not deploy the template repository, only projects created from it
    if: github.repository != 'fastapi/full-stack-fastapi-template'
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false
      - name: Set up Bun
        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
        with:
          bun-version: 1.3.12
      - name: Install frontend dependencies
        run: bun ci
      - name: Build frontend
        run: bun run --filter frontend build
        env:
          # Override frontend/.env so the deployed frontend uses the same origin as the API
          VITE_API_URL: ""
      - name: Set up uv
        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
        with:
          version: "0.11.18"
      - name: Prepare database
        run: uv run bash scripts/prestart.sh
        working-directory: backend
        env:
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
          PROJECT_NAME: ${{ vars.PROJECT_NAME }}
          SECRET_KEY: ${{ secrets.SECRET_KEY }}
          FIRST_SUPERUSER: ${{ vars.FIRST_SUPERUSER }}
          FIRST_SUPERUSER_PASSWORD: ${{ secrets.FIRST_SUPERUSER_PASSWORD }}
      - name: Deploy to FastAPI Cloud
        run: uv run fastapi deploy
        env:
          FASTAPI_CLOUD_TOKEN: ${{ secrets.FASTAPI_CLOUD_TOKEN }}
          FASTAPI_CLOUD_APP_ID: ${{ secrets.FASTAPI_CLOUD_APP_ID }}
@@ -0,0 +1,20 @@
 name: Labels
 on:
  pull_request_target: # zizmor: ignore[dangerous-triggers]
    types:
      - opened
      - synchronize
      - reopened
 permissions: {}
 jobs:
  labeler:
    permissions:
      contents: read
      pull-requests: write
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
    - uses: actions/labeler@bf12e9b00b37c5c0ca2b87b79b2daf7891dbda13 # v7.0.0
    - run: echo "Done adding labels"
@@ -28,7 +28,7 @@ jobs:
          # See: https://github.com/astral-sh/setup-uv/issues/851#issuecomment-4282017837
          version: "0.11.18"
      - run: docker compose down -v --remove-orphans
-      - run: docker compose up -d db mailcatcher
+      - run: docker compose up -d db mailpit
      - name: Migrate DB
        run: uv run bash scripts/prestart.sh
        working-directory: backend
@@ -11,21 +11,20 @@
  - 🔍 [Pydantic](https://docs.pydantic.dev), used by FastAPI, for the data validation and settings management.
  - 💾 [PostgreSQL](https://www.postgresql.org) as the SQL database.
 - 🚀 [React](https://react.dev) for the frontend.
-  - 🧩 Built into the backend application and served by FastAPI on the same domain as the API.
+  - 🧩 Built into the backend image and served by FastAPI on the same domain as the API.
  - 💃 Using TypeScript, hooks, [Vite](https://vitejs.dev), and other parts of a modern frontend stack.
  - 🎨 [Tailwind CSS](https://tailwindcss.com) and [shadcn/ui](https://ui.shadcn.com) for the frontend components.
  - 🤖 An automatically generated frontend client.
  - 🧪 [Playwright](https://playwright.dev) for End-to-End testing.
  - 🦇 Dark mode support.
- ☁️ [FastAPI Cloud](https://fastapicloud.com) for deployment.
+- 🐋 [Docker Compose](https://www.docker.com) for local services and deployment.
 - 🐋 [Docker Compose](https://www.docker.com) for local services and self-hosted deployment.
  - 📞 [Traefik](https://traefik.io) as a reverse proxy with automatic HTTPS.
 - 🔒 Secure password hashing by default.
 - 🔑 JWT (JSON Web Token) authentication.
 - 📫 Email based password recovery.
- 📬 [Mailcatcher](https://mailcatcher.me) for local email testing during development.
+- 📬 [Mailpit](https://mailpit.axllent.org) for local email testing during development.
 - ✅ Tests with [Pytest](https://pytest.org).
- 🚢 Deployment with FastAPI Cloud or self-hosting with Docker Compose and Traefik.
+- 📞 [Traefik](https://traefik.io) as a reverse proxy / load balancer.
 - 🚢 Deployment instructions using Docker Compose with automatic HTTPS provided by Traefik.
 - 🏭 CI (continuous integration) and CD (continuous deployment) based on GitHub Actions.
 ### Dashboard Login
@@ -124,7 +123,17 @@ git merge --continue
 ### Configure
-You can update the local settings in the `.env` file. Before deploying, configure the environment variables and secrets described in the [FastAPI Cloud deployment guide](./deployment.md) or the [Docker Compose deployment guide](./deployment-docker-compose.md). Never deploy with the default `changethis` values.
+You can then update configs in the `.env` files to customize your configurations.
 Before deploying it, make sure you change at least the values for:
 - `SECRET_KEY`
 - `FIRST_SUPERUSER_PASSWORD`
 - `POSTGRES_PASSWORD`
 You can (and should) pass these as environment variables from secrets.
 Read the [deployment.md](./deployment.md) docs for more details.
 ### Generate Secret Keys
@@ -150,13 +159,11 @@ Frontend docs: [frontend/README.md](./frontend/README.md).
 Deployment docs: [deployment.md](./deployment.md).
 Docker Compose deployment: [deployment-docker-compose.md](./deployment-docker-compose.md).
 ## Development
 General development docs: [development.md](./development.md).
-This includes the local FastAPI and Vite workflow, Docker Compose services, `.env` configuration, and more.
+This includes the local FastAPI and Vite workflow, Docker Compose services, custom local domains, `.env` configuration, and more.
 ## Release Notes
@@ -9,10 +9,10 @@
 Run the backend locally and connect it to PostgreSQL in Docker Compose.
-From the project root, start PostgreSQL and Mailcatcher:
+From the project root, start PostgreSQL and Mailpit:
 ```console
-$ docker compose up -d db mailcatcher
+$ docker compose up -d db mailpit
 ```
 Then, from `./backend/`, install the dependencies, prepare the database, and start the development server:
@@ -64,14 +64,14 @@ services:
      - ./backend/htmlcov:/app/backend/htmlcov
    environment:
      FASTAPI_ENV: "development"
-      SMTP_HOST: "mailcatcher"
+      SMTP_HOST: "mailpit"
      SMTP_PORT: "1025"
      SMTP_TLS: "false"
-  mailcatcher:
+  mailpit:
-    image: schickling/mailcatcher
+    image: axllent/mailpit
    ports:
-      - "1080:1080"
+      - "8025:8025"
      - "1025:1025"
  playwright:
@@ -83,13 +83,13 @@ services:
    ipc: host
    depends_on:
      - backend
-      - mailcatcher
+      - mailpit
    environment:
      - FIRST_SUPERUSER=${FIRST_SUPERUSER:?Variable not set}
      - FIRST_SUPERUSER_PASSWORD=${FIRST_SUPERUSER_PASSWORD:?Variable not set}
      - PLAYWRIGHT_BASE_URL=http://backend:8000
      - VITE_API_URL=http://backend:8000
-      - MAILCATCHER_HOST=http://mailcatcher:1080
+      - MAILPIT_HOST=http://mailpit:8025
      # For the reports when run locally
      - PLAYWRIGHT_HTML_HOST=0.0.0.0
      - CI=${CI:-}
@@ -1,129 +0,0 @@
 # FastAPI Project - Docker Compose Deployment
 You can deploy the project to your own remote server with Docker Compose. The deployment configuration includes Traefik to handle HTTPS and route incoming traffic to the application.
 ## Preparation
 * Have a remote server ready and available.
 * Configure DNS records pointing to the server for the application domain and any supporting service subdomains you want to expose, such as `fastapi-project.example.com` and `adminer.fastapi-project.example.com`.
 * Install and configure [Docker](https://docs.docker.com/engine/install/) on the remote server (Docker Engine, not Docker Desktop).
 ## Copy the Code
 ```bash
 rsync -av --exclude=".git/" --filter=":- .gitignore" ./ root@your-server.example.com:/root/code/app/
 ```
 The `--filter=":- .gitignore"` option tells `rsync` to use the same ignore rules as Git, excluding files such as the Python virtual environment.
 ## Configure the Application
 ### Environment Variables
 Set the application domain, project name, and first superuser email:
 ```bash
 export DOMAIN=fastapi-project.example.com
 export PROJECT_NAME="Full Stack FastAPI Project"
 export FIRST_SUPERUSER=admin@example.com
 ```
 You can also configure these environment variables as needed:
 * `SMTP_HOST`: The SMTP server host from your email provider.
 * `SMTP_USER`: The SMTP server user.
 * `EMAILS_FROM_EMAIL`: The email account used to send emails.
 * `SENTRY_DSN`: The DSN for Sentry.
 ### Secrets
 Generate and set secure values for the database password, token signing key, and first superuser password:
 ```bash
 export POSTGRES_PASSWORD="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
 export SECRET_KEY="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
 export FIRST_SUPERUSER_PASSWORD="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
 ```
 To use an authenticated email provider, also set `SMTP_PASSWORD`.
 ## Deploy
 ```bash
 cd /root/code/app/
 docker compose -f compose.yml -f compose.deploy.yml build
 docker compose -f compose.yml -f compose.deploy.yml run --rm backend bash scripts/prestart.sh
 docker compose -f compose.yml -f compose.deploy.yml up -d
 ```
 The `compose.deploy.yml` file adds HTTPS and automatic certificate handling to the shared `compose.yml` configuration. Explicitly listing both files excludes the local settings from `compose.override.yml`.
 The backend Docker image builds the frontend, so the server does not need Bun or prebuilt frontend files.
 ## Deploy with GitHub Actions
 The included `.github/workflows/deploy-docker-compose.yml` workflow runs the deployment commands on the server when manually triggered from GitHub Actions.
 Use a self-hosted runner only for a repository whose contributors and workflow code you trust. GitHub recommends using self-hosted runners with private repositories because workflows execute directly on the runner machine.
 ### Configure Repository Variables and Secrets
 In the repository, go to **Settings** > **Secrets and variables** > **Actions** and add these repository variables:
 * `DOMAIN`
 * `PROJECT_NAME`
 * `FIRST_SUPERUSER`
 To enable emails, add these optional repository variables:
 * `SMTP_HOST`
 * `SMTP_USER`
 * `EMAILS_FROM_EMAIL`
 To enable Sentry, add the optional `SENTRY_DSN` repository variable.
 Add these repository secrets:
 * `POSTGRES_PASSWORD`
 * `SECRET_KEY`
 * `FIRST_SUPERUSER_PASSWORD`
 To use an authenticated email provider, add the optional `SMTP_PASSWORD` repository secret.
 ### Install a Self-Hosted Runner
 On the server, create a dedicated user and grant it access to Docker:
 ```bash
 sudo adduser github
 sudo usermod -aG docker github
 sudo su - github
 ```
 In the GitHub repository, go to **Settings** > **Actions** > **Runners**, select **New self-hosted runner**, choose Linux, and follow the commands GitHub provides to download, configure, and register the runner. Install it in `/home/github/actions-runner`.
 After registering the runner, exit the `github` user session and install the runner as a system service:
 ```bash
 exit
 cd /home/github/actions-runner
 sudo ./svc.sh install github
 sudo ./svc.sh start
 sudo ./svc.sh status
 ```
 See GitHub's guides for [adding a self-hosted runner](https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/add-runners) and [configuring the runner as a service](https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/configure-the-application?platform=linux).
 ### Run the Deployment
 When the runner is online, open the repository's **Actions** tab, select **Deploy with Docker Compose**, and select **Run workflow**.
 ## URLs
 Replace `fastapi-project.example.com` with your domain.
 Application (frontend and API): `https://fastapi-project.example.com`
 Interactive API docs: `https://fastapi-project.example.com/docs`
 Adminer: `https://adminer.fastapi-project.example.com`
@@ -1,97 +1,247 @@
 # FastAPI Project - Deployment
-Deploy the project to [FastAPI Cloud](https://fastapicloud.com) with the included GitHub Actions workflow.
+You can deploy the project using Docker Compose to a remote server.
-## Create the FastAPI Cloud Application
+The deployment Docker Compose configuration includes Traefik to handle HTTPS and route incoming traffic to the application.
-Create an application in FastAPI Cloud and set its [Application Directory](https://fastapicloud.com/docs/builds-and-deployments/application-directory/) to `backend`.
+You can use CI/CD (continuous integration and continuous deployment) systems to deploy automatically, there are already configurations to do it with GitHub Actions.
-Connect a PostgreSQL database using the [Neon](https://fastapicloud.com/docs/integrations/neon-integration/) or [Supabase](https://fastapicloud.com/docs/integrations/supabase-integration/) integration. Both integrations configure a `DATABASE_URL` secret automatically. You can also configure `DATABASE_URL` manually for another PostgreSQL provider.
+But you have to configure a couple things first. 🤓
-## Configure the Application
+## Preparation
-### Environment Variables
+* Have a remote server ready and available. Use a separate server for each environment, for example one for staging and one for production.
 * Configure DNS records pointing to the server for the application domain and any supporting service subdomains you want to expose, e.g. `fastapi-project.example.com` and `adminer.fastapi-project.example.com`.
 * Install and configure [Docker](https://docs.docker.com/engine/install/) on the remote server (Docker Engine, not Docker Desktop).
-Add these required [environment variables](https://fastapicloud.com/docs/builds-and-deployments/environment-variables/) to the FastAPI Cloud application:
+## Deploy the FastAPI Project
-* `PROJECT_NAME`: The name of the project, used in the API documentation and emails.
+You can deploy your FastAPI project with Docker Compose.
 * `FIRST_SUPERUSER`: The email address of the first superuser.
 * `FRONTEND_HOST`: The public URL of the application, such as the generated `https://your-app.fastapicloud.dev` URL or a custom domain.
-To enable emails, add these optional environment variables with values from your email provider:
+**Note**: You might want to jump ahead to the section about Continuous Deployment with GitHub Actions.
-* `SMTP_HOST`
+## Copy the Code
 * `SMTP_USER`
 * `EMAILS_FROM_EMAIL`
-To enable Sentry, configure `SENTRY_DSN`.
+```bash
 rsync -av --exclude=".git/" --filter=":- .gitignore" ./ root@your-server.example.com:/root/code/app/
 ```
-### Secrets
+Note: `--filter=":- .gitignore"` tells `rsync` to use the same rules as git, ignore files ignored by git, like the Python virtual environment.
-Add these required values and mark them as secrets:
+## Environment Variables
-* `SECRET_KEY`: A secret key used to sign security tokens.
+You need to set some environment variables first.
 * `FIRST_SUPERUSER_PASSWORD`: The password of the first superuser.
 * `DATABASE_URL`: The PostgreSQL connection URL, configured automatically when using a database integration.
-To enable emails with an authenticated provider, add `SMTP_PASSWORD` as a secret.
+### Generate secret keys
-You can generate secure values for `SECRET_KEY` and `FIRST_SUPERUSER_PASSWORD` with:
+Some environment variables in the `.env` file have a default value of `changethis`.
 You have to change them with a secret key, to generate secret keys you can run the following command:
 ```bash
 python -c "import secrets; print(secrets.token_urlsafe(32))"
 ```
-## Configure Continuous Deployment
+Copy the content and use that as password / secret key. And run that again to generate another secure key.
-The included `.github/workflows/deploy.yml` workflow builds the frontend, prepares the database, and deploys the application whenever changes are pushed to `master`. You can also run it manually from the **Actions** tab.
+### Required Environment Variables
-Log in to FastAPI Cloud and configure the [deploy token](https://fastapicloud.com/docs/advanced-features/deploy-tokens/) and application ID as GitHub repository secrets:
+Set the `DOMAIN` to your own domain, for example:
 ```bash
-uv run fastapi login
+export DOMAIN=fastapi-project.example.com
 uv run fastapi cloud setup-ci --secrets-only --app-id <your-app-id>
 ```
-If the GitHub CLI is installed and authenticated, the command configures `FASTAPI_CLOUD_TOKEN` and `FASTAPI_CLOUD_APP_ID` automatically. Otherwise, it prints the values so you can add them in your repository under **Settings** > **Secrets and variables** > **Actions**.
+The deployment Docker Compose configuration also uses `DOMAIN` to set the public frontend URL used in links generated by the backend.
-The workflow runs database migrations and creates the first superuser before deploying. In the repository's **Settings** > **Secrets and variables** > **Actions** page, add these repository variables:
+Set the `POSTGRES_PASSWORD` to a secure value:
-* `PROJECT_NAME`
+```bash
 export POSTGRES_PASSWORD="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
 ```
 Set the `SECRET_KEY`, used to sign tokens, to a secure value:
 ```bash
 export SECRET_KEY="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
 ```
 Set the `FIRST_SUPERUSER_PASSWORD` to a secure value:
 ```bash
 export FIRST_SUPERUSER_PASSWORD="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
 ```
 You can set several other environment variables:
 * `PROJECT_NAME`: The name of the project, used in the API for the docs and emails.
 * `FIRST_SUPERUSER`: The email of the first superuser, this superuser will be the one that can create new users.
 * `SMTP_HOST`: The SMTP server host to send emails, this would come from your email provider (E.g. Mailgun, Sparkpost, Sendgrid, etc).
 * `SMTP_USER`: The SMTP server user to send emails.
 * `SMTP_PASSWORD`: The SMTP server password to send emails.
 * `EMAILS_FROM_EMAIL`: The email account to send emails from.
 * `SENTRY_DSN`: The DSN for Sentry, if you are using it.
 ## GitHub Actions Environment Variables
 There are some environment variables only used by GitHub Actions that you can configure:
 * `LATEST_CHANGES`: Used by the GitHub Action [latest-changes](https://github.com/tiangolo/latest-changes) to automatically add release notes based on the PRs merged. It's a personal access token, read the docs for details.
 * `SMOKESHOW_AUTH_KEY`: Used to handle and publish the code coverage using [Smokeshow](https://github.com/samuelcolvin/smokeshow), follow their instructions to create a (free) Smokeshow key.
 ### Deploy with Docker Compose
 With the environment variables in place, you can deploy with Docker Compose:
 ```bash
 cd /root/code/app/
 docker compose -f compose.yml -f compose.deploy.yml build
 docker compose -f compose.yml -f compose.deploy.yml run --rm backend bash scripts/prestart.sh
 docker compose -f compose.yml -f compose.deploy.yml up -d
 ```
 The `compose.deploy.yml` file adds the deployment settings to the shared configuration in `compose.yml`, including HTTPS and automatic certificate handling. Explicitly listing these files also excludes the local development settings in `compose.override.yml`.
 ## Continuous Deployment (CD)
 You can use GitHub Actions to deploy your project automatically. 😎
 There are already two environment deployments configured, `staging` and `production`. Each environment should be deployed to a separate server. 🚀
 ### Install GitHub Actions Runner
 * On your remote server, create a user for your GitHub Actions:
 ```bash
 sudo adduser github
 ```
 * Add Docker permissions to the `github` user:
 ```bash
 sudo usermod -aG docker github
 ```
 * Temporarily switch to the `github` user:
 ```bash
 sudo su - github
 ```
 * Go to the `github` user's home directory:
 ```bash
 cd
 ```
 * [Install a GitHub Action self-hosted runner following the official guide](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners#adding-a-self-hosted-runner-to-a-repository).
 * When asked about labels, add a label for the environment, e.g. `production`. You can also add labels later.
 After installing, the guide would tell you to run a command to start the runner. Nevertheless, it would stop once you terminate that process or if your local connection to your server is lost.
 To make sure it runs on startup and continues running, you can install it as a service. To do that, exit the `github` user and go back to the `root` user:
 ```bash
 exit
 ```
 After you do it, you will be on the previous user again. And you will be on the previous directory, belonging to that user.
 Before being able to go the `github` user directory, you need to become the `root` user (you might already be):
 ```bash
 sudo su
 ```
 * As the `root` user, go to the `actions-runner` directory inside of the `github` user's home directory:
 ```bash
 cd /home/github/actions-runner
 ```
 * Install the self-hosted runner as a service with the user `github`:
 ```bash
 ./svc.sh install github
 ```
 * Start the service:
 ```bash
 ./svc.sh start
 ```
 * Check the status of the service:
 ```bash
 ./svc.sh status
 ```
 You can read more about it in the official guide: [Configuring the self-hosted runner application as a service](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/configuring-the-self-hosted-runner-application-as-a-service).
 ### Configure GitHub Environments
 The deployment workflows use [GitHub Environments](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments) for `staging` and `production`. This enables environment-specific secrets, deployment protection rules (e.g. required reviewers, wait timers), and deployment status tracking.
 To configure them, go to your repository's **Settings** > **Environments** and create the `staging` and `production` environments.
 ### Set Secrets
 For each GitHub Environment (`staging` and `production`), configure the required secrets as [environment secrets](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets#creating-secrets-for-an-environment). Environment secrets are preferred over [repository secrets](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets#creating-secrets-for-a-repository) because they are scoped to the specific environment, reducing exposure and aligning with any protection rules you configure.
 The deployment workflows require these secrets:
 * `DOMAIN`
 * `FIRST_SUPERUSER`
 Add these repository secrets:
 * `DATABASE_URL`
 * `SECRET_KEY`
 * `FIRST_SUPERUSER_PASSWORD`
 * `POSTGRES_PASSWORD`
 * `SECRET_KEY`
-Use the same values configured in FastAPI Cloud. For `DATABASE_URL`, use the connection URL from your database provider. The database must be reachable from GitHub-hosted runners so the preparation step can connect to it.
+To enable emails, configure these additional secrets with the values from your email provider:
-The deployment workflow performs these steps:
+* `SMTP_HOST`
 * `SMTP_USER`
 * `SMTP_PASSWORD`
 * `EMAILS_FROM_EMAIL`
-1. Installs and builds the frontend into `backend/app/frontend`.
+To enable Sentry, configure the `SENTRY_DSN` secret.
-2. Runs `backend/scripts/prestart.sh` to apply database migrations and create the first superuser.
+
-3. Deploys the project with `uv run fastapi deploy`.
+## GitHub Action Deployment Workflows
 There are GitHub Action workflows in the `.github/workflows` directory already configured for deploying to the environments (GitHub Actions runners with the labels):
 * `staging`: after pushing (or merging) to the branch `master`.
 * `production`: after publishing a release.
 Both workflows are associated with their respective GitHub Environments, so deployments will be visible in the repository's **Environments** section and will respect any protection rules you configure.
 ### Prepare a Release
 Install the [PR Submit GitHub App](https://github.com/apps/pr-submit) in your repository to enable the **Prepare Release** workflow.
 Run the workflow manually from the **Actions** tab and select the version bump. It creates a pull request that updates the release notes. When you merge that pull request, the **Create Draft Release** workflow creates a draft GitHub release with the corresponding release notes.
 Review and publish the draft release to trigger the production deployment.
 If you need to add extra environments you could use those as a starting point.
 ## URLs
-Replace `your-app.fastapicloud.dev` with the URL of your FastAPI Cloud application.
+Replace `fastapi-project.example.com` with your domain.
-Application (frontend and API): `https://your-app.fastapicloud.dev`
+### Production
-Interactive API docs: `https://your-app.fastapicloud.dev/docs`
+Application (frontend and API): `https://fastapi-project.example.com`
-## Docker Compose
+Interactive API docs: `https://fastapi-project.example.com/docs`
-For deployment to your own server, see the [Docker Compose deployment guide](./deployment-docker-compose.md).
+Adminer: `https://adminer.fastapi-project.example.com`
-## GitHub Repository Automation
+### Staging
-Install the following GitHub Apps to enable the included repository automation:
+Application (frontend and API): `https://staging.fastapi-project.example.com`
-* [Latest Changes](https://github.com/apps/latest-changes) updates `release-notes.md` when a pull request is merged.
+Interactive API docs: `https://staging.fastapi-project.example.com/docs`
 * [PR Push](https://github.com/apps/pr-push) lets the pre-commit workflow push automated fixes to pull request branches.
 * [PR Submit](https://github.com/apps/pr-submit) lets the **Bump pre-commit hooks** and **Prepare Release** workflows create pull requests.
-To publish code coverage with [Smokeshow](https://github.com/samuelcolvin/smokeshow), add `SMOKESHOW_AUTH_KEY` as a repository secret.
+Adminer: `https://adminer.staging.fastapi-project.example.com`
@@ -2,12 +2,12 @@
 ## Local Development
-For local development, run PostgreSQL and Mailcatcher with Docker Compose, and run the FastAPI and Vite development servers locally.
+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 mailcatcher
+docker compose up -d db mailpit
 ```
 Then, from the `backend` directory, install the dependencies and prepare the database:
@@ -38,7 +38,7 @@ Backend API: <http://localhost:8000>
 Automatic interactive API documentation with Swagger UI: <http://localhost:8000/docs>
-Mailcatcher: <http://localhost:1080>
+Mailpit: <http://localhost:8025>
 The frontend development server uses the backend at `http://localhost:8000`, as configured in `frontend/.env`.
@@ -71,15 +71,15 @@ 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>
+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.
-## Mailcatcher
+## Mailpit
-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>.
+[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 env vars
@@ -156,7 +156,7 @@ biome check..............................................................Passed
 ## URLs
-The deployed URLs use these same paths, but with your own domain.
+The production or staging URLs would use these same paths, but with your own domain.
 ### Development URLs
@@ -172,4 +172,4 @@ Adminer: <http://localhost:8080>
 Traefik UI: <http://localhost:8090>
-MailCatcher: <http://localhost:1080>
+Mailpit: <http://localhost:8025>
@@ -1,2 +1,2 @@
 VITE_API_URL=http://localhost:8000
-MAILCATCHER_HOST=http://localhost:1080
+MAILPIT_HOST=http://localhost:8025
@@ -33,10 +33,6 @@ If you are developing an API-only app and want to remove the frontend, you can d
 * In the `compose.override.yml` file, remove the `playwright` service.
 * In the `.github/workflows/deploy.yml` file, remove the **Set up Bun**, **Install frontend dependencies**, and **Build frontend** steps.
 * In the `.fastapicloudignore` file, remove the `!backend/app/frontend/` entry.
 Done, you have a frontend-less (api-only) app. 🤓
 ## Generate Client
@@ -1,5 +1,5 @@
 import { expect, test } from "@playwright/test"
-import { findLastEmail } from "./utils/mailcatcher"
+import { emailUrl, findLastEmail } from "./utils/mailpit"
 import { randomEmail, randomPassword } from "./utils/random"
 import { logInUser, signUpNewUser } from "./utils/user"
@@ -46,13 +46,11 @@ test("User can reset password successfully using the link", async ({
  const emailData = await findLastEmail({
    request,
-    filter: (e) => e.recipients.includes(`<${email}>`),
+    query: `to:${email}`,
    timeout: 5000,
  })
-  await page.goto(
+  await page.goto(emailUrl(emailData))
    `${process.env.MAILCATCHER_HOST}/messages/${emailData.id}.html`,
  )
  const selector = 'a[href*="/reset-password?token="]'
@@ -99,13 +97,11 @@ test("Weak new password validation", async ({ page, request }) => {
  const emailData = await findLastEmail({
    request,
-    filter: (e) => e.recipients.includes(`<${email}>`),
+    query: `to:${email}`,
    timeout: 5000,
  })
-  await page.goto(
+  await page.goto(emailUrl(emailData))
    `${process.env.MAILCATCHER_HOST}/messages/${emailData.id}.html`,
  )
  const selector = 'a[href*="/reset-password?token="]'
  const url = await page.getAttribute(selector, "href")
@@ -1,62 +0,0 @@
 import type { APIRequestContext } from "@playwright/test"
 type Email = {
  id: number
  recipients: string[]
  subject: string
 }
 async function findEmail({
  request,
  filter,
 }: {
  request: APIRequestContext
  filter?: (email: Email) => boolean
 }) {
  const response = await request.get(`${process.env.MAILCATCHER_HOST}/messages`)
  let emails = await response.json()
  if (filter) {
    emails = emails.filter(filter)
  }
  const email = emails[emails.length - 1]
  if (email) {
    return email as Email
  }
  return null
 }
 export function findLastEmail({
  request,
  filter,
  timeout = 5000,
 }: {
  request: APIRequestContext
  filter?: (email: Email) => boolean
  timeout?: number
 }) {
  const timeoutPromise = new Promise<never>((_, reject) =>
    setTimeout(
      () => reject(new Error("Timeout while trying to get latest email")),
      timeout,
    ),
  )
  const checkEmails = async () => {
    while (true) {
      const emailData = await findEmail({ request, filter })
      if (emailData) {
        return emailData
      }
      // Wait for 100ms before checking again
      await new Promise((resolve) => setTimeout(resolve, 100))
    }
  }
  return Promise.race([timeoutPromise, checkEmails()])
 }
@@ -0,0 +1,59 @@
 import type { APIRequestContext } from "@playwright/test"
 type Address = {
  Name: string
  Address: string
 }
 type Email = {
  ID: string
  To: Address[]
  Subject: string
 }
 async function findEmail({
  request,
  query,
 }: {
  request: APIRequestContext
  query: string
 }) {
  const response = await request.get(
    `${process.env.MAILPIT_HOST}/api/v1/search`,
    {
      params: { query, limit: 1 },
    },
  )
  const { messages }: { messages: Email[] } = await response.json()
  return messages[0] ?? null
 }
 export async function findLastEmail({
  request,
  query,
  timeout = 5000,
 }: {
  request: APIRequestContext
  query: string
  timeout?: number
 }) {
  const deadline = Date.now() + timeout
  while (Date.now() < deadline) {
    const email = await findEmail({ request, query })
    if (email) {
      return email
    }
    await new Promise((resolve) => setTimeout(resolve, 100))
  }
  throw new Error(`Timeout while trying to get the latest email for "${query}"`)
 }
 export function emailUrl(email: Email) {
  return `${process.env.MAILPIT_HOST}/view/${email.ID}.html`
 }
@@ -2,25 +2,8 @@
 ## Latest Changes
 ## 0.12.0 (2026-08-12)
 ### Features
 * ☁️ Add FastAPI Cloud deployment. PR [#2438](https://github.com/fastapi/full-stack-fastapi-template/pull/2438) by [@tiangolo](https://github.com/tiangolo).
 ### Fixes
 * 🐳 Include frontend assets in Docker build context. PR [#2440](https://github.com/fastapi/full-stack-fastapi-template/pull/2440) by [@tiangolo](https://github.com/tiangolo).
 ### Internal
 * 👷 Migrate automatic labels to Latest Changes. PR [#2439](https://github.com/fastapi/full-stack-fastapi-template/pull/2439) by [@tiangolo](https://github.com/tiangolo).
 ## 0.11.1 (2026-08-11)
 ### Refactors
 * ♻️ Simplify Docker Compose deployment. PR [#2435](https://github.com/fastapi/full-stack-fastapi-template/pull/2435) by [@tiangolo](https://github.com/tiangolo).
 * ♻️ Migrate to `DATABASE_URL` instead of separate variables. PR [#2184](https://github.com/fastapi/full-stack-fastapi-template/pull/2184) by [@patrick91](https://github.com/patrick91).
 ### Internal
`@@ -1,2 +1,2 @@`
	`VITE_API_URL=http://localhost:8000`	`VITE_API_URL=http://localhost:8000`
	`MAILCATCHER_HOST=http://localhost:1080`	`MAILPIT_HOST=http://localhost:8025`