amir/full-stack-fastapi-template
1
0
Fork 0
mirror of https://github.com/fastapi/full-stack-fastapi-template.git synced 2026-11-03 20:36:27 +00:00
Code Issues Packages Projects Releases Wiki Activity

Fix conflicts

Browse Source
This commit is contained in:
Alejandra
2026-08-13 18:07:40 +02:00
parent 0eff31727b c350936d28
commit e0d5fcc411
16 changed files with 371 additions and 507 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.dockerignore
-1
View File
@@ -1,7 +1,6 @@
.git .git
**/__pycache__ **/__pycache__
**/.venv **/.venv
backend/app/frontend
backend/htmlcov backend/htmlcov
frontend/blob-report frontend/blob-report
frontend/dist frontend/dist
.fastapicloudignore
+2
View File
@@ -0,0 +1,2 @@
.env
!backend/app/frontend/
.github/labeler.yml
-25
View File
@@ -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/**'
.github/latest-changes.yml
+12
View File
@@ -0,0 +1,12 @@
auto-labels:
docs:
- exclude: frontend/**
- exclude: backend/**
- exclude: .github/**
- exclude: scripts/**
- '**/*.md'
internal:
- .github/**
- scripts/**
- .gitignore
- .pre-commit-config.yaml
.github/workflows/deploy-docker-compose.yml
+41
View File
@@ -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
.github/workflows/deploy-production.yml
-37
View File
@@ -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
.github/workflows/deploy-staging.yml
-37
View File
@@ -1,37 +0,0 @@
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
.github/workflows/deploy.yml
+54
View File
@@ -0,0 +1,54 @@
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 }}
.github/workflows/labeler.yml
-20
View File
@@ -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"
README.md
+19 -114
View File
@@ -1,8 +1,7 @@
# Full Stack FastAPI Template # Full Stack FastAPI Template
<a href="https://github.com/fastapi/full-stack-fastapi-template/actions?query=workflow%3A%22Test+Docker+Compose%22" target="_blank"><img src="https://github.com/fastapi/full-stack-fastapi-template/workflows/Test%20Docker%20Compose/badge.svg" alt="Test Docker Compose"></a> [![Test Docker Compose](../../actions/workflows/test-docker-compose.yml/badge.svg)](../../actions/workflows/test-docker-compose.yml)
<a href="https://github.com/fastapi/full-stack-fastapi-template/actions?query=workflow%3A%22Test+Backend%22" target="_blank"><img src="https://github.com/fastapi/full-stack-fastapi-template/workflows/Test%20Backend/badge.svg" alt="Test Backend"></a> [![Test Backend](../../actions/workflows/test-backend.yml/badge.svg)](../../actions/workflows/test-backend.yml)
<a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/fastapi/full-stack-fastapi-template" target="_blank"><img src="https://coverage-badge.samuelcolvin.workers.dev/fastapi/full-stack-fastapi-template.svg" alt="Coverage"></a>
## Technology Stack and Features ## Technology Stack and Features
@@ -11,141 +10,45 @@
- 🔍 [Pydantic](https://docs.pydantic.dev), used by FastAPI, for the data validation and settings management. - 🔍 [Pydantic](https://docs.pydantic.dev), used by FastAPI, for the data validation and settings management.
- 💾 [PostgreSQL](https://www.postgresql.org) as the SQL database. - 💾 [PostgreSQL](https://www.postgresql.org) as the SQL database.
- 🚀 [React](https://react.dev) for the frontend. - 🚀 [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. - 💃 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. - 🎨 [Tailwind CSS](https://tailwindcss.com) and [shadcn/ui](https://ui.shadcn.com) for the frontend components.
- 🤖 An automatically generated frontend client. - 🤖 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. - 🦇 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. - 🔒 Secure password hashing by default.
- 🔑 JWT (JSON Web Token) authentication. - 🔑 JWT (JSON Web Token) authentication.
- 📫 Email based password recovery. - 📫 Email-based password recovery.
- 📬 [Mailpit](https://mailpit.axllent.org) for local email testing during development. - 📬 [Mailpit](https://mailpit.axllent.org) for local email testing during development.
- ✅ Tests with [Pytest](https://pytest.org). - ✅ 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.
- 🏭 CI (continuous integration) and CD (continuous deployment) based on GitHub Actions. - 🏭 CI (continuous integration) and CD (continuous deployment) based on GitHub Actions.
### Dashboard Login ### Dashboard Login
[![Dashboard login screenshot](img/login.png)](https://github.com/fastapi/full-stack-fastapi-template) ![Dashboard login screenshot](img/login.png)
### Dashboard - Admin ### Dashboard - Admin
[![Admin dashboard screenshot](img/dashboard.png)](https://github.com/fastapi/full-stack-fastapi-template) ![Admin dashboard screenshot](img/dashboard.png)
### Dashboard - Items ### 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 ### 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 ### 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. Click the **Use this template** button at the top of this page to create a new repository.
✨ 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 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
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.
## Backend Development ## Backend Development
@@ -157,13 +60,15 @@ Frontend docs: [frontend/README.md](./frontend/README.md).
## Deployment ## Deployment
Deployment docs: [deployment.md](./deployment.md). FastAPI Cloud deployment: [deployment.md](./deployment.md).
Self-hosted deployment with Docker Compose: [deployment-docker-compose.md](./deployment-docker-compose.md).
## Development ## Development
General development docs: [development.md](./development.md). 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 ## Release Notes
backend/README.md
+8 -8
View File
@@ -58,19 +58,19 @@ To open a shell in the backend container:
$ docker compose exec backend bash $ docker compose exec backend bash
``` ```
## Backend tests ## Backend Tests
To test the backend from the `backend` directory, run: To test the backend from the `backend` directory, run:
```console ```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: 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 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: For example, to stop on first error:
@@ -88,7 +88,7 @@ docker compose exec backend bash scripts/tests-start.sh -x
### Test Coverage ### 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 ## 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 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: To preview the emails while editing them, start the dev server from the root of the project:
deployment-docker-compose.md
+129
View File
@@ -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`
deployment.md
+51 -201
View File
@@ -1,247 +1,97 @@
# FastAPI Project - Deployment # 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
You can use CI/CD (continuous integration and continuous deployment) systems to deploy automatically, there are already configurations to do it with GitHub Actions. 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. Use a separate server for each environment, for example one for staging and one for production. ### Environment Variables
* 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).
## 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 To enable Sentry, configure `SENTRY_DSN`.
rsync -av --exclude=".git/" --filter=":- .gitignore" ./ root@your-server.example.com:/root/code/app/
```
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 can generate secure values for `SECRET_KEY` and `FIRST_SUPERUSER_PASSWORD` with:
You have to change them with a secret key, to generate secret keys you can run the following command:
```bash ```bash
python -c "import secrets; print(secrets.token_urlsafe(32))" 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 ```bash
export DOMAIN=fastapi-project.example.com uv run fastapi login
uv run fastapi cloud setup-ci --secrets-only --app-id <your-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 * `PROJECT_NAME`
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` * `FIRST_SUPERUSER`
* `FIRST_SUPERUSER_PASSWORD`
* `POSTGRES_PASSWORD` Add these repository secrets:
* `DATABASE_URL`
* `SECRET_KEY` * `SECRET_KEY`
* `FIRST_SUPERUSER_PASSWORD`
To enable emails, configure these additional secrets with the values from your email provider: 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.
* `SMTP_HOST` The deployment workflow performs these steps:
* `SMTP_USER`
* `SMTP_PASSWORD`
* `EMAILS_FROM_EMAIL`
To enable Sentry, configure the `SENTRY_DSN` secret. 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.
## GitHub Action Deployment Workflows 3. Deploys the project with `uv run fastapi deploy`.
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 ## URLs
Replace `fastapi-project.example.com` with your domain. Replace `your-app.fastapicloud.dev` with the URL of your FastAPI Cloud application.
### Production Application (frontend and API): `https://your-app.fastapicloud.dev`
Application (frontend and API): `https://fastapi-project.example.com` Interactive API docs: `https://your-app.fastapicloud.dev/docs`
Interactive API docs: `https://fastapi-project.example.com/docs` ## Docker Compose
Adminer: `https://adminer.fastapi-project.example.com` For deployment to your own server, see the [Docker Compose deployment guide](./deployment-docker-compose.md).
### Staging ## GitHub Repository Automation
Application (frontend and API): `https://staging.fastapi-project.example.com` Install the following GitHub Apps to enable the included repository automation:
Interactive API docs: `https://staging.fastapi-project.example.com/docs` * [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.
Adminer: `https://adminer.staging.fastapi-project.example.com` To publish code coverage with [Smokeshow](https://github.com/samuelcolvin/smokeshow), add `SMOKESHOW_AUTH_KEY` as a repository secret.
development.md
+16 -53
View File
@@ -81,11 +81,11 @@ Stop a locally running FastAPI server before starting the Compose backend becaus
[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>. [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 ## 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. 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 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 The project uses [prek](https://prek.j178.dev/), a modern alternative to [pre-commit](https://pre-commit.com/), for code linting and formatting.
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.
You can find a file `.pre-commit-config.yaml` with configurations at the root of the project. 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. `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. From the project root, install the Git hook so that `prek` runs automatically before each commit:
Using `uv`, you could do it with (make sure you are inside `backend` folder):
```bash ```bash
❯ uv run prek install -f uv run prek install -f
prek installed at `../.git/hooks/pre-commit`
``` ```
The `-f` flag forces the installation, in case there was already a `pre-commit` hook previously installed. 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 ```bash
git commit 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 files from the project root:
you can also run `prek` manually on all the files, you can do it using `uv` with:
```bash ```bash
❯ uv run prek run --all-files 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
``` ```
## URLs
The production or staging URLs would use these same paths, but with your own domain.
### Development URLs
Development URLs, for local development.
Application: <http://localhost:8000>
Automatic Interactive Docs (Swagger UI): <http://localhost:8000/docs>
Automatic Alternative Docs (ReDoc): <http://localhost:8000/redoc>
Adminer: <http://localhost:8080>
Traefik UI: <http://localhost:8090>
Mailpit: <http://localhost:8025>
frontend/README.md
+18 -11
View File
@@ -1,27 +1,29 @@
# FastAPI Project - Frontend # 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 ## Requirements
- [Bun](https://bun.sh/) (recommended) or [Node.js](https://nodejs.org/) - [Bun](https://bun.sh/)
## Quick Start ## Quick Start
From the project root, install the dependencies and start the frontend development server:
```bash ```bash
bun install bun install
bun run dev bun run dev
``` ```
* Then open your browser at http://localhost:5173/. Then open <http://localhost:5173/> 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. 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`. 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: If you are developing an API-only app and want to remove the frontend, you can do it easily:
@@ -33,13 +35,17 @@ 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 `compose.override.yml` file, remove the `playwright` service.
Done, you have a frontend-less (api-only) app. 🤓 * 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 now have an API-only app. 🤓
## Generate Client ## Generate Client
### Automatically ### Automatically
* From the top level project directory, run the script: * From the project root, run the script:
```bash ```bash
bash ./scripts/generate-client.sh bash ./scripts/generate-client.sh
@@ -61,7 +67,7 @@ bun run generate-client
* Commit the changes. * 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 ## Using a Remote API
@@ -78,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: The frontend code is structured as follows:
* `frontend/src` - The main frontend code. * `frontend/src` - The main frontend code.
* `frontend/src/assets` - Static assets. * `frontend/public` - Static assets.
* `frontend/src/client` - The generated OpenAPI client. * `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/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 ## End-to-End Testing with Playwright
release-notes.md
+21
View File
@@ -2,8 +2,29 @@
## Latest Changes ## 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
* ☁️ 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 ### 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). * ♻️ 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 ### Internal