Deploying

It is recommended to read this in full before doing anything!
Every step in docker install should be done.

First make sure to create a docker-compose.override.yml file corresponding to your needs, see the docker-compose docs. This file will be used in conjunction with the default docker-compose.yml file, an example is given, you can copy it as a bootstrap for your own.

$ cp docker-compose.override.yml{_example,}

Make sure to set good values for cpus, mem_limit and mem_reservation on your workers services or the server will have poor performances and the users experience will be greatly degraded.
Be wary that docker stores everything in /var/lib/docker rather than the current path, so it's advisable to either override the volumes configuration or the whole docker data directory if your system partition is small.

Change at the very least the admin password (DJANGO_SU_PASSWORD) and the secret key (SECRET_KEY) in the variables.env file before building!
SECRET_KEY is used for cryptographic signing, should be unique and unpredictable.
Change DJANGO_SU_EMAIL to receive error emails.
DJANGO_FROM_EMAIL is the sender of outbound emails.

The variables.env file is passed to the containers, some configurations need to be passed directly to the docker-compose build through environment variables on the host.
Configure exim (message transfer agent) with:

$ export MAIL_PRIMARY_HOST=domainname.com

Setup the task queues to avoid having your tasks being killed because of oom, by setting the concurrency on both main and low-priority workers. They should more or less match your mem_limit (cf production.yml) divided by the maximum memory taken by the tasks consumed by these workers respectively. This is assuming trying to have decent performance on a single machine, if running a swarm and each worker has its own machine the limits don't make sense.

$ export CELERY_MAIN_CONC=4
$ export CELERY_LOW_CONC=4

A decent strategy is to start quite low and rise over time if no processes get killed.

Alternatively you can create a file called .env and write those variables in it, docker will pick them up automatically.

Update the code:

$ git pull origin master

Pull the images:

$ docker-compose pull

Run everything:

$ docker-compose up -d

Setting the domain name:

When sending emails we don't always have access to the request, which means we don't know on which domain to generate urls for. You can set it up here: /admin/sites/site/.
It may become a build option at some point.

Backing up the database:

For example to do it everyday at 3am you could add in your crontab:

0 3 * * * docker exec -u postgres escriptorium_db_1 pg_dump -Fc escriptorium > /path/to/backups/db-$(date +"\%Y\%m\%d-\%H\%M").dump

In case you changed $POSTGRES_USER, $POSTGRES_DB make sure to change them accordingly, since cron doesn't have access to those.

And send it away a while later:

0 4 * * * rsync -r /path/to/backups/ distantuser@distantserver:/distant/path/to/backups

Using a gpu

First make sure to have a supported distribution here.
Then install the latest nvidia drivers. For Debian 10 the easiest way is to use the buster backports.

$ echo deb http://deb.debian.org/debian buster-backports main > /etc/apt/sources.list  
$ sudo apt-get update   
$ apt-get install -t buster-backports nvidia-driver  

insert additional steps here

Since docker-compose doesn't have a way to use Docker's --gpus argument, we have to use the deprecated nvidia-docker2 along with the old docker-compose file api 2.4.

You can follow the installation process explained here, but instead of nvidia-container-toolkit install nvidia-docker2.

Beware that this may overwrite your /etc/docker/daemon.json configuration so make sure to update it as needed.

Then in your production.yml file, uncomment the dedicated GPU environment variables and configurations.
To make use of more gpus, simply add more workers following the same configuration.
Then rebuild & run the containers.

Using SSL

Install certbot

$ sudo apt-get install certbot

Generate certificates (change the domain names accordingly)

$ certbot certonly -d escriptorium.fr -d www.escriptorium.fr --standalone --preferred-challenges http

In production.yml, update the nginx configuration to use ssl.conf, uncomment the 443 port and mount the directory countaining the certificates:

    nginx:
      restart: always
      build:
        args:
          - NGINX_CONF=ssl.conf
      ports:
        - "80:80"
        - "443:443"
      volumes:
        - /etc/letsencrypt:/etc/letsencrypt

Copy and update nginx/ssl_certificates.conf to match your mounted volume.