☁️ Add FastAPI Cloud deployment (#2438)

2026-11-03 12:29:42 +00:00 · 2026-08-11 23:16:35 +02:00
parent ddb3c34f19
commit 2d8fb3e4de
7 changed files with 271 additions and 198 deletions
@@ -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`