254 lines
8.5 KiB
Markdown
254 lines
8.5 KiB
Markdown
# FastAPI Project - Deployment
|
|
|
|
You can deploy the project using Docker Compose to a remote server.
|
|
|
|
This project expects you to have a Traefik proxy handling communication to the outside world and HTTPS certificates.
|
|
|
|
You can use CI/CD (continuous integration and continuous deployment) systems to deploy automatically, there are already configurations to do it with GitHub Actions.
|
|
|
|
But you have to configure a couple things first. 🤓
|
|
|
|
## Preparation
|
|
|
|
* Have a remote server ready and available.
|
|
* Configure the DNS records of your domain to point to the IP of the server you just created.
|
|
* Install and configure [Docker](https://docs.docker.com/engine/install/).
|
|
* Create a remote directory to store your code, for example:
|
|
|
|
```bash
|
|
mkdir -p /root/code/fastapi-project/
|
|
```
|
|
|
|
## Public Traefik
|
|
|
|
We need a Traefik proxy to handle incoming connections and HTTPS certificates.
|
|
|
|
You need to do these next steps only once.
|
|
|
|
### Traefik Docker Compose
|
|
|
|
Copy the Traefik Docker Compose file to your server, to your code directory. You could do it with `rsync`:
|
|
|
|
```bash
|
|
rsync -a docker-compose.traefik.yml root@your-server.example.com:/root/code/fastapi-project/
|
|
```
|
|
|
|
### Traefik Public Network
|
|
|
|
This Traefik will expect a Docker "public network" named `traefik-public` to communicate with your stack(s).
|
|
|
|
This way, there will be a single public Traefik proxy that handles the communication (HTTP and HTTPS) with the outside world, and then behind that, you could have one or more stacks with different domains, even if they are on the same single server.
|
|
|
|
To create a Docker "public network" named `traefik-public` run:
|
|
|
|
```bash
|
|
docker network create traefik-public
|
|
```
|
|
|
|
### Traefik Environment Variables
|
|
|
|
The Traefik Docker Compose file expects some environment variables to be set.
|
|
|
|
* Create the username for HTTP Basic Auth, e.g.:
|
|
|
|
```bash
|
|
export USERNAME=admin
|
|
```
|
|
|
|
* Create an environment variable with the password for HTTP Basic Auth, e.g.:
|
|
|
|
```bash
|
|
export PASSWORD=changethis
|
|
```
|
|
|
|
* Use openssl to generate the "hashed" version of the password for HTTP Basic Auth and store it in an environment variable:
|
|
|
|
```bash
|
|
export HASHED_PASSWORD=$(openssl passwd -apr1 $PASSWORD)
|
|
```
|
|
|
|
* Create an environment variable with the domain name for your server, e.g.:
|
|
|
|
```bash
|
|
export DOMAIN=fastapi-project.example.com
|
|
```
|
|
|
|
* Create an environment variable with the email for Let's Encrypt, e.g.:
|
|
|
|
```bash
|
|
export EMAIL=admin@example.com
|
|
```
|
|
|
|
**Note**: you need to set a different email, an email `@example.com` won't work.
|
|
|
|
### Start the Traefik Docker Compose
|
|
|
|
Now with the environment variables set and the `docker-compose.traefik.yml` in place, you can start the Traefik Docker Compose:
|
|
|
|
```bash
|
|
docker compose -f docker-compose.traefik.yml up -d
|
|
```
|
|
|
|
## Deploy the FastAPI Project
|
|
|
|
Now that you have Traefik in place you can deploy your FastAPI project with Docker Compose.
|
|
|
|
## Environment Variables
|
|
|
|
You need to set some environment variables first.
|
|
|
|
Set the `ENVIRONMENT`, by default `local` (for development), but when deploying to a server you would put something like `staging` or `production`:
|
|
|
|
```bash
|
|
export ENVIRONMENT=production
|
|
```
|
|
|
|
Set the `DOMAIN`, by default `localhost` (for development), but when deploying you would use your own domain, for example:
|
|
|
|
```bash
|
|
export DOMAIN=fastapi-project.example.com
|
|
```
|
|
|
|
You can set several variables, like:
|
|
|
|
* `ENVIRONMENT`: The current deployment environment, like `staging` or `production`.
|
|
* `DOMAIN`: The current deployment domain, for example `fastapi-project.example.com`.
|
|
* `BACKEND_CORS_ORIGINS`: A list of allowed CORS origins separated by commas.
|
|
* `SECRET_KEY`: The secret key for the FastAPI project, used to sign tokens.
|
|
* `FIRST_SUPERUSER`: The email of the first superuser, this superuser will be the one that can create new users.
|
|
* `FIRST_SUPERUSER_PASSWORD`: The password of the first superuser.
|
|
* `USERS_OPEN_REGISTRATION`: Whether to allow open registration of 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.
|
|
* `POSTGRES_SERVER`: The hostname of the PostgreSQL server. You can leave the default of `db`, provided by the same Docker Compose. You normally wouldn't need to change this unless you are using a third-party provider.
|
|
* `POSTGRES_PASSWORD`: The Postgres password.
|
|
* `POSTGRES_USER`: The Postgres user, you can leave the default.
|
|
* `POSTGRES_DB`: The database name to use for this application. You can leave the default of `app`.
|
|
* `PGADMIN_DEFAULT_EMAIL`: The default email for pgAdmin.
|
|
* `PGADMIN_DEFAULT_PASSWORD`: The default password for pgAdmin.
|
|
* `SENTRY_DSN`: The DSN for Sentry, if you are using it.
|
|
* `FLOWER_BASIC_AUTH`: The HTTP Basic Auth for Flower.
|
|
|
|
### Deploy with Docker Compose
|
|
|
|
With the environment variables in place, you can deploy with Docker Compose:
|
|
|
|
```bash
|
|
docker compose -f docker-compose.yml up -d
|
|
```
|
|
|
|
For production you wouldn't want to have the overrides in `docker-compose.override.yml`, that's why we explicitly specify `docker-compose.yml` as the file to use.
|
|
|
|
## Continuous Deployment (CD)
|
|
|
|
You can use GitHub Actions to deploy your project automatically. 😎
|
|
|
|
You can have multiple environment deployments.
|
|
|
|
There are already two environments configured, `staging` and `production`. 🚀
|
|
|
|
### Install GitHub Actions Runner
|
|
|
|
* On your remote server, if you are running as the `root` user, create a user for your GitHub Actions:
|
|
|
|
```bash
|
|
adduser github
|
|
```
|
|
|
|
* Add Docker permissions to the `github` user:
|
|
|
|
```bash
|
|
usermod -aG docker github
|
|
```
|
|
|
|
* Temporarily switch to the `github` user:
|
|
|
|
```bash
|
|
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`.
|
|
|
|
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 would be on the `root` user again. And you will be on the previous directory, belonging to the `root` user.
|
|
|
|
* Go to the `actions-runner` directory inside of the `github` user's home directory:
|
|
|
|
```bash
|
|
cd /home/github/actions-runner
|
|
```
|
|
|
|
* From there, [install the GitHub Actions runner service following the official guide](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/configuring-the-self-hosted-runner-application-as-a-service#installing-the-service):
|
|
|
|
```bash
|
|
./svc.sh install github
|
|
```
|
|
|
|
* Start the service:
|
|
|
|
```bash
|
|
./svc.sh start
|
|
```
|
|
|
|
### Set Secrets
|
|
|
|
On your repository, configure secrets for the environment variables you need, the same ones described above, including `DOMAIN`, `SECRET_KEY`, etc. Follow the [official GitHub guide for setting repository secrets](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository).
|
|
|
|
## 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.
|
|
|
|
If you need to add extra environments you could use those as starting point.
|
|
|
|
## URLs
|
|
|
|
Replace `fastapi-project.example.com` with your domain.
|
|
|
|
### Main Traefik Dashboard
|
|
|
|
Traefik UI: `https://traefik.fastapi-project.example.com`
|
|
|
|
### Production
|
|
|
|
Frontend: `https://fastapi-project.example.com`
|
|
|
|
Backend API docs: `https://fastapi-project.example.com/docs`
|
|
|
|
Backend API base URL: `https://fastapi-project.example.com/api/`
|
|
|
|
PGAdmin: `https://pgadmin.fastapi-project.example.com`
|
|
|
|
Flower: `https://flower.fastapi-project.example.com`
|
|
|
|
### Staging
|
|
|
|
Frontend: `https://staging.fastapi-project.example.com`
|
|
|
|
Backend API docs: `https://staging.fastapi-project.example.com/docs`
|
|
|
|
Backend API base URL: `https://staging.fastapi-project.example.com/api/`
|
|
|
|
PGAdmin: `https://staging.pgadmin.fastapi-project.example.com`
|
|
|
|
Flower: `https://staging.flower.fastapi-project.example.com`
|