From 6b9fa4113c6ce32b143b8c850785c5431af00848 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Tue, 11 Aug 2026 21:35:45 +0200 Subject: [PATCH 01/12] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20Simplify=20Docker=20?= =?UTF-8?q?Compose=20deployment=20(#2435)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/deploy-production.yml | 37 ------------ .../{deploy-staging.yml => deploy.yml} | 9 ++- deployment.md | 60 ++++--------------- development.md | 2 +- 4 files changed, 17 insertions(+), 91 deletions(-) delete mode 100644 .github/workflows/deploy-production.yml rename .github/workflows/{deploy-staging.yml => deploy.yml} (91%) diff --git a/.github/workflows/deploy-production.yml b/.github/workflows/deploy-production.yml deleted file mode 100644 index e62fe953..00000000 --- a/.github/workflows/deploy-production.yml +++ /dev/null @@ -1,37 +0,0 @@ -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 diff --git a/.github/workflows/deploy-staging.yml b/.github/workflows/deploy.yml similarity index 91% rename from .github/workflows/deploy-staging.yml rename to .github/workflows/deploy.yml index 1c35943d..e1f6640c 100644 --- a/.github/workflows/deploy-staging.yml +++ b/.github/workflows/deploy.yml @@ -1,21 +1,20 @@ -name: Deploy to Staging +name: Deploy on: push: branches: - master + paths-ignore: + - release-notes.md 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 + runs-on: self-hosted env: DOMAIN: ${{ secrets.DOMAIN }} SECRET_KEY: ${{ secrets.SECRET_KEY }} diff --git a/deployment.md b/deployment.md index 331ccbac..c1e5adce 100644 --- a/deployment.md +++ b/deployment.md @@ -4,13 +4,13 @@ You can deploy the project using Docker Compose to a remote server. The deployment Docker Compose configuration includes Traefik to handle HTTPS and route incoming traffic to the application. -You can use CI/CD (continuous integration and continuous deployment) systems to deploy automatically, there are already configurations to do it with GitHub Actions. +The included GitHub Actions workflow can deploy the application automatically. But you have to configure a couple things first. ๐Ÿค“ ## Preparation -* Have a remote server ready and available. Use a separate server for each environment, for example one for staging and one for production. +* 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, 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). @@ -82,12 +82,15 @@ You can set several other environment variables: * `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 +## GitHub Repository Automation -There are some environment variables only used by GitHub Actions that you can configure: +Install the following GitHub Apps to enable the included repository automation: -* `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. +* [Latest Changes](https://github.com/apps/latest-changes) updates `release-notes.md` when a pull request is merged. +* [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. ### Deploy with Docker Compose @@ -106,7 +109,7 @@ The `compose.deploy.yml` file adds the deployment settings to the shared configu 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. ๐Ÿš€ +The included `deploy.yml` workflow deploys the application whenever changes are pushed to `master`, including when a pull request is merged. ๐Ÿš€ ### Install GitHub Actions Runner @@ -136,8 +139,6 @@ 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: @@ -180,17 +181,9 @@ cd /home/github/actions-runner 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 +### Set Repository Secrets -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: +In your repository, go to **Settings** > **Secrets and variables** > **Actions** and add the following [repository secrets](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets#creating-secrets-for-a-repository): * `DOMAIN` * `FIRST_SUPERUSER` @@ -207,41 +200,12 @@ To enable emails, configure these additional secrets with the values from your e To enable Sentry, configure the `SENTRY_DSN` secret. -## 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 `fastapi-project.example.com` with your domain. -### Production - 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` - -### Staging - -Application (frontend and API): `https://staging.fastapi-project.example.com` - -Interactive API docs: `https://staging.fastapi-project.example.com/docs` - -Adminer: `https://adminer.staging.fastapi-project.example.com` diff --git a/development.md b/development.md index 198a5ca3..07eb0491 100644 --- a/development.md +++ b/development.md @@ -156,7 +156,7 @@ biome check..............................................................Passed ## URLs -The production or staging URLs would use these same paths, but with your own domain. +The deployed URLs use these same paths, but with your own domain. ### Development URLs From eae2d6701d67084b677fb4030832a2e9babe0c10 Mon Sep 17 00:00:00 2001 From: "latest-changes[bot]" <313495250+latest-changes[bot]@users.noreply.github.com> Date: Tue, 11 Aug 2026 19:35:48 +0000 Subject: [PATCH 02/12] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/release-notes.md b/release-notes.md index 3b7ada2a..7de3940d 100644 --- a/release-notes.md +++ b/release-notes.md @@ -4,6 +4,7 @@ ### 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 From ddb3c34f1956c028bcb10985ce60c3c147c52d8c Mon Sep 17 00:00:00 2001 From: "pr-submit[bot]" <314742883+pr-submit[bot]@users.noreply.github.com> Date: Tue, 11 Aug 2026 21:57:14 +0200 Subject: [PATCH 03/12] =?UTF-8?q?=F0=9F=94=96=20Release=20version=200.11.1?= =?UTF-8?q?=20(#2437)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: pr-submit[bot] --- release-notes.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/release-notes.md b/release-notes.md index 7de3940d..b7298389 100644 --- a/release-notes.md +++ b/release-notes.md @@ -2,6 +2,8 @@ ## Latest Changes +## 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). From 2d8fb3e4defa61d84ac8bd23faa93b626cda7f3c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Tue, 11 Aug 2026 23:16:35 +0200 Subject: [PATCH 04/12] =?UTF-8?q?=E2=98=81=EF=B8=8F=20Add=20FastAPI=20Clou?= =?UTF-8?q?d=20deployment=20(#2438)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .fastapicloudignore | 2 + .github/workflows/deploy-docker-compose.yml | 41 ++++ .github/workflows/deploy.yml | 52 +++-- README.md | 25 +-- deployment-docker-compose.md | 129 ++++++++++++ deployment.md | 216 +++++--------------- frontend/README.md | 4 + 7 files changed, 271 insertions(+), 198 deletions(-) create mode 100644 .fastapicloudignore create mode 100644 .github/workflows/deploy-docker-compose.yml create mode 100644 deployment-docker-compose.md diff --git a/.fastapicloudignore b/.fastapicloudignore new file mode 100644 index 00000000..de3842d1 --- /dev/null +++ b/.fastapicloudignore @@ -0,0 +1,2 @@ +.env +!backend/app/frontend/ diff --git a/.github/workflows/deploy-docker-compose.yml b/.github/workflows/deploy-docker-compose.yml new file mode 100644 index 00000000..4062687b --- /dev/null +++ b/.github/workflows/deploy-docker-compose.yml @@ -0,0 +1,41 @@ +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 diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index e1f6640c..82e7efd2 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -6,31 +6,49 @@ on: - master paths-ignore: - release-notes.md + workflow_dispatch: permissions: contents: read jobs: deploy: - # Do not deploy in the main repository, only in user projects - if: github.repository_owner != 'fastapi' - runs-on: self-hosted - 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 }} + # 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 - - 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 + - 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 }} diff --git a/README.md b/README.md index 010e8fc9..f12724cf 100644 --- a/README.md +++ b/README.md @@ -11,20 +11,21 @@ - ๐Ÿ” [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 image and served by FastAPI on the same domain as the API. + - ๐Ÿงฉ Built into the backend application 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. -- ๐Ÿ‹ [Docker Compose](https://www.docker.com) for local services and deployment. +- โ˜๏ธ [FastAPI Cloud](https://fastapicloud.com) for 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. - โœ… Tests with [Pytest](https://pytest.org). -- ๐Ÿ“ž [Traefik](https://traefik.io) as a reverse proxy / load balancer. -- ๐Ÿšข Deployment instructions using Docker Compose with automatic HTTPS provided by Traefik. +- ๐Ÿšข Deployment with FastAPI Cloud or self-hosting with Docker Compose and Traefik. - ๐Ÿญ CI (continuous integration) and CD (continuous deployment) based on GitHub Actions. ### Dashboard Login @@ -123,17 +124,7 @@ git merge --continue ### Configure -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. +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. ### Generate Secret Keys @@ -159,11 +150,13 @@ 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, custom local domains, `.env` configuration, and more. +This includes the local FastAPI and Vite workflow, Docker Compose services, `.env` configuration, and more. ## Release Notes diff --git a/deployment-docker-compose.md b/deployment-docker-compose.md new file mode 100644 index 00000000..5c43fd54 --- /dev/null +++ b/deployment-docker-compose.md @@ -0,0 +1,129 @@ +# 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` diff --git a/deployment.md b/deployment.md index c1e5adce..8e445ce5 100644 --- a/deployment.md +++ b/deployment.md @@ -1,86 +1,90 @@ # FastAPI Project - Deployment -You can deploy the project using Docker Compose to a remote server. +Deploy the project to [FastAPI Cloud](https://fastapicloud.com) with the included GitHub Actions workflow. -The deployment Docker Compose configuration includes Traefik to handle HTTPS and route incoming traffic to the application. +## Create the FastAPI Cloud Application -The included GitHub Actions workflow can deploy the application automatically. +Create an application in FastAPI Cloud and set its [Application Directory](https://fastapicloud.com/docs/builds-and-deployments/application-directory/) to `backend`. -But you have to configure a couple things first. ๐Ÿค“ +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. -## Preparation +## Configure the Application -* 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, 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). +### Environment Variables -## Deploy the FastAPI Project +Add these required [environment variables](https://fastapicloud.com/docs/builds-and-deployments/environment-variables/) to the FastAPI Cloud application: -You can deploy your FastAPI project with Docker Compose. +* `PROJECT_NAME`: The name of the project, used in the API documentation and emails. +* `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. -**Note**: You might want to jump ahead to the section about Continuous Deployment with GitHub Actions. +To enable emails, add these optional environment variables with values from your email provider: -## Copy the Code +* `SMTP_HOST` +* `SMTP_USER` +* `EMAILS_FROM_EMAIL` -```bash -rsync -av --exclude=".git/" --filter=":- .gitignore" ./ root@your-server.example.com:/root/code/app/ -``` +To enable Sentry, configure `SENTRY_DSN`. -Note: `--filter=":- .gitignore"` tells `rsync` to use the same rules as git, ignore files ignored by git, like the Python virtual environment. +### Secrets -## Environment Variables +Add these required values and mark them as secrets: -You need to set some environment variables first. +* `SECRET_KEY`: A secret key used to sign security tokens. +* `FIRST_SUPERUSER_PASSWORD`: The password of the first superuser. +* `DATABASE_URL`: The PostgreSQL connection URL, configured automatically when using a database integration. -### Generate secret keys +To enable emails with an authenticated provider, add `SMTP_PASSWORD` as a secret. -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: +You can generate secure values for `SECRET_KEY` and `FIRST_SUPERUSER_PASSWORD` with: ```bash python -c "import secrets; print(secrets.token_urlsafe(32))" ``` -Copy the content and use that as password / secret key. And run that again to generate another secure key. +## Configure Continuous Deployment -### Required Environment Variables +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. -Set the `DOMAIN` to your own domain, for example: +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: ```bash -export DOMAIN=fastapi-project.example.com +uv run fastapi login +uv run fastapi cloud setup-ci --secrets-only --app-id ``` -The deployment Docker Compose configuration also uses `DOMAIN` to set the public frontend URL used in links generated by the backend. +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**. -Set the `POSTGRES_PASSWORD` to a secure value: +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: -```bash -export POSTGRES_PASSWORD="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')" -``` +* `PROJECT_NAME` +* `FIRST_SUPERUSER` -Set the `SECRET_KEY`, used to sign tokens, to a secure value: +Add these repository secrets: -```bash -export SECRET_KEY="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')" -``` +* `DATABASE_URL` +* `SECRET_KEY` +* `FIRST_SUPERUSER_PASSWORD` -Set the `FIRST_SUPERUSER_PASSWORD` to a secure value: +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. -```bash -export FIRST_SUPERUSER_PASSWORD="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')" -``` +The deployment workflow performs these steps: -You can set several other environment variables: +1. Installs and builds the frontend into `backend/app/frontend`. +2. Runs `backend/scripts/prestart.sh` to apply database migrations and create the first superuser. +3. Deploys the project with `uv run fastapi deploy`. -* `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. +## URLs + +Replace `your-app.fastapicloud.dev` with the URL of your FastAPI Cloud application. + +Application (frontend and API): `https://your-app.fastapicloud.dev` + +Interactive API docs: `https://your-app.fastapicloud.dev/docs` + +## Docker Compose + +For deployment to your own server, see the [Docker Compose deployment guide](./deployment-docker-compose.md). ## GitHub Repository Automation @@ -91,121 +95,3 @@ Install the following GitHub Apps to enable the included repository automation: * [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. - -### 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. ๐Ÿ˜Ž - -The included `deploy.yml` workflow deploys the application whenever changes are pushed to `master`, including when a pull request is merged. ๐Ÿš€ - -### 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). - -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). - -### Set Repository Secrets - -In your repository, go to **Settings** > **Secrets and variables** > **Actions** and add the following [repository secrets](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets#creating-secrets-for-a-repository): - -* `DOMAIN` -* `FIRST_SUPERUSER` -* `FIRST_SUPERUSER_PASSWORD` -* `POSTGRES_PASSWORD` -* `SECRET_KEY` - -To enable emails, configure these additional secrets with the values from your email provider: - -* `SMTP_HOST` -* `SMTP_USER` -* `SMTP_PASSWORD` -* `EMAILS_FROM_EMAIL` - -To enable Sentry, configure the `SENTRY_DSN` secret. - -## 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` diff --git a/frontend/README.md b/frontend/README.md index 65e7b0c5..af7cfb6b 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -33,6 +33,10 @@ 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 From a2d2d1810870a1fe28001832de8e4fdc3a3e4940 Mon Sep 17 00:00:00 2001 From: "latest-changes[bot]" <313495250+latest-changes[bot]@users.noreply.github.com> Date: Tue, 11 Aug 2026 21:16:38 +0000 Subject: [PATCH 05/12] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- release-notes.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/release-notes.md b/release-notes.md index b7298389..5bf6aee8 100644 --- a/release-notes.md +++ b/release-notes.md @@ -2,6 +2,10 @@ ## Latest Changes +### Features + +* โ˜๏ธ Add FastAPI Cloud deployment. PR [#2438](https://github.com/fastapi/full-stack-fastapi-template/pull/2438) by [@tiangolo](https://github.com/tiangolo). + ## 0.11.1 (2026-08-11) ### Refactors From 7f11815e4390f5c3422d46570fb1fab99dfa0c43 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Wed, 12 Aug 2026 09:19:46 +0200 Subject: [PATCH 06/12] =?UTF-8?q?=F0=9F=91=B7=20Migrate=20automatic=20labe?= =?UTF-8?q?ls=20to=20Latest=20Changes=20(#2439)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/labeler.yml | 25 ------------------------- .github/latest-changes.yml | 12 ++++++++++++ .github/workflows/labeler.yml | 20 -------------------- 3 files changed, 12 insertions(+), 45 deletions(-) delete mode 100644 .github/labeler.yml create mode 100644 .github/latest-changes.yml delete mode 100644 .github/workflows/labeler.yml diff --git a/.github/labeler.yml b/.github/labeler.yml deleted file mode 100644 index ed657c23..00000000 --- a/.github/labeler.yml +++ /dev/null @@ -1,25 +0,0 @@ -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/**' diff --git a/.github/latest-changes.yml b/.github/latest-changes.yml new file mode 100644 index 00000000..89034c74 --- /dev/null +++ b/.github/latest-changes.yml @@ -0,0 +1,12 @@ +auto-labels: + docs: + - exclude: frontend/** + - exclude: backend/** + - exclude: .github/** + - exclude: scripts/** + - '**/*.md' + internal: + - .github/** + - scripts/** + - .gitignore + - .pre-commit-config.yaml diff --git a/.github/workflows/labeler.yml b/.github/workflows/labeler.yml deleted file mode 100644 index bc990e96..00000000 --- a/.github/workflows/labeler.yml +++ /dev/null @@ -1,20 +0,0 @@ -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" From ec86250a213d8302e0f698dae42623b8ea7cae7b Mon Sep 17 00:00:00 2001 From: "latest-changes[bot]" <313495250+latest-changes[bot]@users.noreply.github.com> Date: Wed, 12 Aug 2026 07:19:49 +0000 Subject: [PATCH 07/12] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- release-notes.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/release-notes.md b/release-notes.md index 5bf6aee8..00c95503 100644 --- a/release-notes.md +++ b/release-notes.md @@ -6,6 +6,10 @@ * โ˜๏ธ Add FastAPI Cloud deployment. PR [#2438](https://github.com/fastapi/full-stack-fastapi-template/pull/2438) 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 From de2ed05b109ccd8867f6eb09ec5dc7c1bf9d0021 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Wed, 12 Aug 2026 09:28:43 +0200 Subject: [PATCH 08/12] =?UTF-8?q?=F0=9F=90=B3=20Include=20frontend=20asset?= =?UTF-8?q?s=20in=20Docker=20build=20context=20(#2440)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .dockerignore | 1 - 1 file changed, 1 deletion(-) diff --git a/.dockerignore b/.dockerignore index 825db1de..c892b070 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,7 +1,6 @@ .git **/__pycache__ **/.venv -backend/app/frontend backend/htmlcov frontend/blob-report frontend/dist From 98fb606b57454da40eb91850e94372a9d0df483a Mon Sep 17 00:00:00 2001 From: "latest-changes[bot]" <313495250+latest-changes[bot]@users.noreply.github.com> Date: Wed, 12 Aug 2026 07:28:45 +0000 Subject: [PATCH 09/12] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- release-notes.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/release-notes.md b/release-notes.md index 00c95503..0abb1102 100644 --- a/release-notes.md +++ b/release-notes.md @@ -6,6 +6,10 @@ * โ˜๏ธ 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). From 84c5a9e11a9e58262599e3d772f5386924e02ca7 Mon Sep 17 00:00:00 2001 From: "pr-submit[bot]" <314742883+pr-submit[bot]@users.noreply.github.com> Date: Wed, 12 Aug 2026 08:46:45 +0000 Subject: [PATCH 10/12] =?UTF-8?q?=F0=9F=94=96=20Release=20version=200.12.0?= =?UTF-8?q?=20(#2441)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: pr-submit[bot] --- release-notes.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/release-notes.md b/release-notes.md index 0abb1102..9ee44f19 100644 --- a/release-notes.md +++ b/release-notes.md @@ -2,6 +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). From 42b4ca0586790d86295c04b277e7315f50ed9e06 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Wed, 12 Aug 2026 11:25:40 +0200 Subject: [PATCH 11/12] =?UTF-8?q?=F0=9F=93=9D=20Simplify=20project=20docum?= =?UTF-8?q?entation=20(#2442)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 114 ++++++--------------------------------------- backend/README.md | 16 +++---- development.md | 69 +++++++-------------------- frontend/README.md | 25 +++++----- 4 files changed, 51 insertions(+), 173 deletions(-) diff --git a/README.md b/README.md index f12724cf..3b1ddffd 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,7 @@ # Full Stack FastAPI Template -Test Docker Compose -Test Backend -Coverage +[![Test Docker Compose](../../actions/workflows/test-docker-compose.yml/badge.svg)](../../actions/workflows/test-docker-compose.yml) +[![Test Backend](../../actions/workflows/test-backend.yml/badge.svg)](../../actions/workflows/test-backend.yml) ## Technology Stack and Features @@ -15,128 +14,41 @@ - ๐Ÿ’ƒ 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. + - ๐Ÿงช [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 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. +- ๐Ÿ“ซ Email-based password recovery. - ๐Ÿ“ฌ [Mailcatcher](https://mailcatcher.me) for local email testing during development. - โœ… Tests with [Pytest](https://pytest.org). -- ๐Ÿšข Deployment with FastAPI Cloud or self-hosting with Docker Compose and Traefik. - ๐Ÿญ CI (continuous integration) and CD (continuous deployment) based on GitHub Actions. ### Dashboard Login -[![Dashboard login screenshot](img/login.png)](https://github.com/fastapi/full-stack-fastapi-template) +![Dashboard login screenshot](img/login.png) ### Dashboard - Admin -[![Admin dashboard screenshot](img/dashboard.png)](https://github.com/fastapi/full-stack-fastapi-template) +![Admin dashboard screenshot](img/dashboard.png) ### Dashboard - Items -[![Items dashboard screenshot](img/dashboard-items.png)](https://github.com/fastapi/full-stack-fastapi-template) +![Items dashboard screenshot](img/dashboard-items.png) ### Dashboard - Dark Mode -[![Dark mode dashboard screenshot](img/dashboard-dark.png)](https://github.com/fastapi/full-stack-fastapi-template) +![Dark mode dashboard screenshot](img/dashboard-dark.png) ### Interactive API Documentation -[![API docs](img/docs.png)](https://github.com/fastapi/full-stack-fastapi-template) +![API docs](img/docs.png) -## How To Use It +## How to Use It -You can **just fork or clone** this repository and use it as is. - -โœจ It just works. โœจ - -### How to Use a Private Repository - -If you want to have a private repository, GitHub won't allow you to simply fork it as it doesn't allow changing the visibility of forks. - -But you can do the following: - -- Create a new GitHub repo, for example `my-full-stack`. -- Clone this repository manually, set the name with the name of the project you want to use, for example `my-full-stack`: - -```bash -git clone git@github.com:fastapi/full-stack-fastapi-template.git my-full-stack -``` - -- Enter into the new directory: - -```bash -cd my-full-stack -``` - -- Set the new origin to your new repository, copy it from the GitHub interface, for example: - -```bash -git remote set-url origin git@github.com:octocat/my-full-stack.git -``` - -- Add this repo as another "remote" to allow you to get updates later: - -```bash -git remote add upstream git@github.com:fastapi/full-stack-fastapi-template.git -``` - -- Push the code to your new repository: - -```bash -git push -u origin master -``` - -### Update From the Original Template - -After cloning the repository, and after doing changes, you might want to get the latest changes from this original template. - -- Make sure you added the original repository as a remote, you can check it with: - -```bash -git remote -v - -origin git@github.com:octocat/my-full-stack.git (fetch) -origin git@github.com:octocat/my-full-stack.git (push) -upstream git@github.com:fastapi/full-stack-fastapi-template.git (fetch) -upstream git@github.com:fastapi/full-stack-fastapi-template.git (push) -``` - -- Pull the latest changes without merging: - -```bash -git pull --no-commit upstream master -``` - -This will download the latest changes from this template without committing them, that way you can check everything is right before committing. - -- If there are conflicts, solve them in your editor. - -- Once you are done, commit the changes: - -```bash -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. - -### Generate Secret Keys - -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))" -``` - -Copy the content and use that as password / secret key. And run that again to generate another secure key. +Click the **Use this template** button at the top of this page to create a new repository. ## Backend Development @@ -148,9 +60,9 @@ Frontend docs: [frontend/README.md](./frontend/README.md). ## Deployment -Deployment docs: [deployment.md](./deployment.md). +FastAPI Cloud deployment: [deployment.md](./deployment.md). -Docker Compose deployment: [deployment-docker-compose.md](./deployment-docker-compose.md). +Self-hosted deployment with Docker Compose: [deployment-docker-compose.md](./deployment-docker-compose.md). ## Development diff --git a/backend/README.md b/backend/README.md index f4536194..c8605ffb 100644 --- a/backend/README.md +++ b/backend/README.md @@ -58,19 +58,19 @@ To open a shell in the backend container: $ docker compose exec backend bash ``` -## Backend tests +## Backend Tests To test the backend from the `backend` directory, run: ```console -$ uv run bash ./scripts/test.sh +$ uv run bash scripts/test.sh ``` -The tests run with Pytest, modify and add tests to `./backend/tests/`. +The tests run with Pytest. Modify existing tests or add new ones in `./backend/tests/`. -If you use GitHub Actions the tests will run automatically. +If you use GitHub Actions, the tests will run automatically. -### Test running stack +### Test a Running Stack If your stack is already up and you just want to run the tests, you can use: @@ -78,7 +78,7 @@ 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. +The `/app/backend/scripts/tests-start.sh` script 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: @@ -88,7 +88,7 @@ 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. +When the tests run, they generate `htmlcov/index.html`. Open it in your browser to inspect the test coverage. ## Migrations @@ -128,7 +128,7 @@ If you don't want to start with the default models and want to remove them / mod The email templates are written with [React Email](https://react.email) in `./packages/react-email/`. The `emails` directory holds one component per email and the `ui` directory holds the shared components (layout, heading, button, link, callout). -The rendered HTML in `./backend/app/email-templates/` is generated from those components, it is what the application sends, and it shouldn't be edited by hand. +The rendered HTML in `./backend/app/email-templates/` is generated from those components. It is what the application sends and should not be edited by hand. To preview the emails while editing them, start the dev server from the root of the project: diff --git a/development.md b/development.md index 07eb0491..2cce9d12 100644 --- a/development.md +++ b/development.md @@ -81,11 +81,11 @@ Stop a locally running FastAPI server before starting the Compose backend becaus 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 . -## Docker Compose files and env vars +## Docker Compose Files and Environment Variables -There is a main `compose.yml` file with all the configurations that apply to the whole stack, it is used automatically by `docker compose`. +The main `compose.yml` file contains the configuration shared by the whole stack. Docker Compose loads it automatically. -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.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. @@ -97,79 +97,42 @@ After changing variables, make sure you restart the stack: docker compose watch ``` -## The .env file +## The `.env` File -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. +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. -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. +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). -One way to do it could be to add each environment variable to your CI/CD system. +## Pre-commit Hooks and Code Linting -## Pre-commits and code linting - -we are using a tool called [prek](https://prek.j178.dev/) (modern alternative to [Pre-commit](https://pre-commit.com/)) 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. +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 +### Install `prek` to Run Automatically `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): +From the project root, install the Git hook so that `prek` runs automatically before each commit: ```bash -โฏ uv run prek install -f -prek installed at `../.git/hooks/pre-commit` +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, e.g. with: +Now whenever you try to commit, for example with: ```bash 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. +`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. -Then you can `git add` the modified/fixed files again and now you can commit. +### Run `prek` Manually -#### Running prek hooks manually - -you can also run `prek` manually on all the files, you can do it using `uv` with: +You can also run `prek` manually on all files from the project root: ```bash -โฏ 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 +uv run prek run --all-files ``` - -## URLs - -The deployed URLs use these same paths, but with your own domain. - -### Development URLs - -Development URLs, for local development. - -Application: - -Automatic Interactive Docs (Swagger UI): - -Automatic Alternative Docs (ReDoc): - -Adminer: - -Traefik UI: - -MailCatcher: diff --git a/frontend/README.md b/frontend/README.md index af7cfb6b..5055e35c 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -1,27 +1,29 @@ # FastAPI Project - Frontend -The frontend is built with [Vite](https://vitejs.dev/), [React](https://reactjs.org/), [TypeScript](https://www.typescriptlang.org/), [TanStack Query](https://tanstack.com/query), [TanStack Router](https://tanstack.com/router) and [Tailwind CSS](https://tailwindcss.com/). +The frontend is built with [Vite](https://vitejs.dev/), [React](https://react.dev/), [TypeScript](https://www.typescriptlang.org/), [TanStack Query](https://tanstack.com/query), [TanStack Router](https://tanstack.com/router), [Tailwind CSS](https://tailwindcss.com/), and [shadcn/ui](https://ui.shadcn.com/). ## Requirements -- [Bun](https://bun.sh/) (recommended) or [Node.js](https://nodejs.org/) +- [Bun](https://bun.sh/) ## Quick Start +From the project root, install the dependencies and start the frontend development server: + ```bash bun install bun run dev ``` -* Then open your browser at http://localhost:5173/. +Then open in your browser. Run `uv run bash scripts/prestart.sh` and `uv run fastapi dev` from the `backend` directory, with PostgreSQL running in Docker Compose. See [../development.md](../development.md) for the complete setup. To serve the frontend with FastAPI, run `bun run build` from the `frontend` directory and open `http://localhost:8000`. -Check the file `package.json` to see other available options. +Check `frontend/package.json` to see the other available commands. -### Removing the frontend +## Removing the Frontend If you are developing an API-only app and want to remove the frontend, you can do it easily: @@ -37,13 +39,13 @@ If you are developing an API-only app and want to remove the frontend, you can d * In the `.fastapicloudignore` file, remove the `!backend/app/frontend/` entry. -Done, you have a frontend-less (api-only) app. ๐Ÿค“ +Done, you now have an API-only app. ๐Ÿค“ ## Generate Client ### Automatically -* From the top level project directory, run the script: +* From the project root, run the script: ```bash bash ./scripts/generate-client.sh @@ -65,7 +67,7 @@ bun run generate-client * Commit the changes. -Notice that everytime the backend changes (changing the OpenAPI schema), you should follow these steps again to update the frontend client. +Regenerate the client whenever backend changes affect the OpenAPI schema. ## Using a Remote API @@ -82,11 +84,12 @@ Then, when you run the frontend, it will use that URL as the base URL for the AP The frontend code is structured as follows: * `frontend/src` - The main frontend code. -* `frontend/src/assets` - Static assets. +* `frontend/public` - Static assets. * `frontend/src/client` - The generated OpenAPI client. -* `frontend/src/components` - The different components of the frontend. +* `frontend/src/components` - The components of the frontend, including the shadcn/ui components in `frontend/src/components/ui`. * `frontend/src/hooks` - Custom hooks. -* `frontend/src/routes` - The different routes of the frontend which include the pages. +* `frontend/src/lib` - Shared frontend utilities. +* `frontend/src/routes` - The frontend routes and pages. ## End-to-End Testing with Playwright From c350936d2888ef16ff4f5549684fd8db54935a89 Mon Sep 17 00:00:00 2001 From: "latest-changes[bot]" <313495250+latest-changes[bot]@users.noreply.github.com> Date: Wed, 12 Aug 2026 09:25:43 +0000 Subject: [PATCH 12/12] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- release-notes.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/release-notes.md b/release-notes.md index 9ee44f19..e8b78bbf 100644 --- a/release-notes.md +++ b/release-notes.md @@ -2,6 +2,10 @@ ## Latest Changes +### Docs + +* ๐Ÿ“ Simplify project documentation. PR [#2442](https://github.com/fastapi/full-stack-fastapi-template/pull/2442) by [@tiangolo](https://github.com/tiangolo). + ## 0.12.0 (2026-08-12) ### Features