Deployment - geosolutions-it/digital-twin-toolbox GitHub Wiki

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.

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.
  • Configure a wildcard subdomain for your domain, so that you can have multiple subdomains for different services, e.g. *.dtt-project.example.com. This will be useful for accessing different components, like traefik.dtt-project.example.com, etc. And also for staging, like staging.dtt-project.example.com, etc.
  • Install and configure Docker on the remote server (Docker Engine, not Docker Desktop).

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

  • Create a remote directory to store your Traefik Docker Compose file:
mkdir -p /root/code/traefik-public/

Copy the Traefik Docker Compose file to your server. You could do it by running the command rsync in your local terminal:

rsync -a docker-compose.traefik.yml [email protected]:/root/code/traefik-public/

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 the following command in your remote server:

docker network create traefik-public

Traefik Environment Variables

The Traefik Docker Compose file expects some environment variables to be set in your terminal before starting it. You can do it by running the following commands in your remote server.

  • Create the username for HTTP Basic Auth, e.g.:
export USERNAME=admin
  • Create an environment variable with the password for HTTP Basic Auth, e.g.:
export PASSWORD=changethis
  • Use openssl to generate the "hashed" version of the password for HTTP Basic Auth and store it in an environment variable:
export HASHED_PASSWORD=$(openssl passwd -apr1 $PASSWORD)

To verify that the hashed password is correct, you can print it:

echo $HASHED_PASSWORD
  • Create an environment variable with the domain name for your server, e.g.:
export DOMAIN=dtt-project.example.com
  • Create an environment variable with the email for Let's Encrypt, e.g.:
export [email protected]

Note: you need to set a different email, an email @example.com won't work.

Start the Traefik Docker Compose

Go to the directory where you copied the Traefik Docker Compose file in your remote server:

cd /root/code/traefik-public/

Now with the environment variables set and the docker-compose.traefik.yml in place, you can start the Traefik Docker Compose running the following command:

docker compose -f docker-compose.traefik.yml up -d

Deploy the Project

Now that you have Traefik in place you can deploy your project with Docker Compose.

Environment Variables

All the project configuration lives in the .env file, which the Docker Compose files load automatically (both for variable interpolation and via env_file). Create it from the provided template and edit the values:

cp .env.copy .env

Set the ENVIRONMENT, by default local (for development), but when deploying to a server you would put something like staging or production:

ENVIRONMENT=production

Set the DOMAIN, by default localhost (for development), but when deploying you would use your own domain, for example:

DOMAIN=dtt-project.example.com

[!NOTE] If you deploy through a CI/CD system you can also inject these as environment variables instead of editing the .env file.

In the same .env file you can set several variables, like:

  • PROJECT_NAME: The name of the project, used in the API for the docs and emails.
  • STACK_NAME: The name of the stack used for Docker Compose labels and project name, this should be different for staging, production, etc. You could use the same domain replacing dots with dashes, e.g. dtt-project-example-com and staging-dtt-project-example-com.
  • BACKEND_CORS_ORIGINS: A list of allowed CORS origins separated by commas.
  • SECRET_KEY: The secret key for the 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.
  • 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_PORT: The port of the PostgreSQL server. You can leave the default. 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.
  • POSTGRES_TASKS_DB: The database name used to store the background tasks state. You can leave the default of tasks.
  • SENTRY_DSN: The DSN for Sentry, if you are using it.
  • DOCKER_IMAGE_BACKEND, DOCKER_IMAGE_FRONTEND, DOCKER_IMAGE_WORKER_VECTOR, DOCKER_IMAGE_WORKER_POINT_CLOUD: The Docker registry images to pull/build for each component.
  • TAG: The image tag to use, e.g. latest or a specific release.
  • CELERY_WORKER_CONCURRENCY: Number of concurrent tasks each worker processes.
  • DTT_ENABLE_USERS_MANAGEMENT: When set to False it removes user management; uploads become available to everybody and all actions are performed as the default superuser. Set to False only in controlled environments.

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.

Deploy with Docker Compose

With the environment variables in place, you can deploy with the compose.sh helper using the --prod flag and starting the workers you need:

./scripts/compose.sh --prod --workers vector,point-cloud -- up -d

For production you wouldn't want to have the overrides in docker-compose.override.yml, that's why the --prod flag excludes it.

URLs

Replace dtt-project.example.com with your domain.

Main Traefik Dashboard

Traefik UI: https://traefik.dtt-project.example.com

Production

Frontend: https://dtt-project.example.com

Backend API docs: https://dtt-project.example.com/docs

Backend API base URL: https://dtt-project.example.com/api/

Staging

Frontend: https://staging.dtt-project.example.com

Backend API docs: https://staging.dtt-project.example.com/docs

Backend API base URL: https://staging.dtt-project.example.com/api/