full-stack-fastapi-template/deployment.md

FastAPI Project - Deployment

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.

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.
• 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 on the remote server (Docker Engine, not Docker Desktop).

Deploy the FastAPI Project

You can deploy your FastAPI project with Docker Compose.

Note: You might want to jump ahead to the section about Continuous Deployment with GitHub Actions.

Copy the Code

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.

Environment Variables

You need to set some environment variables first.

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:

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.

Required Environment Variables

Set the DOMAIN to your own domain, for example:

export DOMAIN=fastapi-project.example.com

The deployment Docker Compose configuration also uses DOMAIN to set the public frontend URL used in links generated by the backend.

Set the POSTGRES_PASSWORD to a secure value:

export POSTGRES_PASSWORD="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"

Set the SECRET_KEY, used to sign tokens, to a secure value:

export SECRET_KEY="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"

Set the FIRST_SUPERUSER_PASSWORD to a secure value:

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 Repository Automation

Install the following GitHub Apps to enable the included repository automation:

• Latest Changes updates release-notes.md when a pull request is merged.
• PR Push lets the pre-commit workflow push automated fixes to pull request branches.
• PR Submit lets the Bump pre-commit hooks and Prepare Release workflows create pull requests.

To publish code coverage with 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:

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:

sudo adduser github

• Add Docker permissions to the github user:

sudo usermod -aG docker github

• Temporarily switch to the github user:

sudo su - github

• Go to the github user's home directory:

cd

• Install a GitHub Action self-hosted runner following the official guide.

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:

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):

sudo su

• As the root user, go to the actions-runner directory inside of the github user's home directory:

cd /home/github/actions-runner

• Install the self-hosted runner as a service with the user github:

./svc.sh install github

• Start the service:

./svc.sh start

• Check the status of the service:

./svc.sh status

You can read more about it in the official guide: 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:

• 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