nginx: Renew certificate

In a Docker installation with nginx as the reverse proxy (alternative to Traefik or older installations), the procedure depends on whether the certificate was obtained from Let’s Encrypt with Certbot or purchased from a certificate authority. For the standard installation with Traefik, see Traefik: Renew certificate →.

Let’s Encrypt (Certbot) #

This section applies if the certificate was obtained with Certbot in standalone mode as described in SSL Certificates - Certbot →.

It may happen that Certbot has not requested a new certificate for various reasons. The renewal can also be triggered manually. Port 80 must be free for this, so nginx is stopped for the duration of the renewal:

sudo certbot renew --pre-hook "/usr/bin/docker compose -f /opt/relution/compose.yaml down nginx" --post-hook "/usr/bin/docker compose -f /opt/relution/compose.yaml up --detach nginx"

For older installations with docker-compose.yml, the path is adjusted to the installation. Alternatively, nginx is stopped beforehand in the directory of the Compose file (by default /opt/relution) with sudo docker compose down nginx and started again afterwards with sudo docker compose up --detach nginx. nginx only delivers the new certificate after the restart. For testing, the command can first be run with --dry-run.

After the renewal, Certbot lists the existing certificates with their expiry date:

sudo certbot certificates

Finally, the Relution web interface is opened in the browser and the padlock icon in the address bar is used to check whether nginx delivers the new certificate with the new expiry date.

Purchased certificate #

The certificate chain (server.pem) and the private key (server.key) are first prepared as described in Renew a purchased certificate →. They are then put in place for nginx as follows.

Place the files #

In a Docker installation with nginx, both files are located in the /opt/relution directory by default. Before the replacement, the existing files are backed up so that they can be restored in case of problems:

cd /opt/relution
sudo cp server.pem server.pem.old
sudo cp server.key server.key.old

The new server.pem file and, if applicable, server.key are then copied to the directory, overwriting the existing ones. Access to the private key is then restricted to its owner:

sudo chmod 600 /opt/relution/server.key

Check the paths in the nginx configuration #

The nginx container reads the certificate and the key from the files mounted in the Compose file. In current installations, the file is named compose.yaml (in the /opt/relution directory), in older installations docker-compose.yml. The mounts are listed in the nginx: block under volumes::

services:
  …

  nginx:
    image: nginx:stable
    …

    volumes:
      - "/opt/relution/relution-nginx.conf:/etc/nginx/conf.d/relution-nginx.conf"
      - "/opt/relution/server.pem:/etc/nginx/server.pem"
      - "/opt/relution/server.key:/etc/nginx/server.key"

The path on the server is to the left of the colon, the path in the container to the right. Older installations use relative paths such as ./server.pem; the files are then located in the same directory as the Compose file.

In the nginx configuration relution-nginx.conf, the ssl_certificate and ssl_certificate_key entries in the server block for port 443 refer to the paths in the container:

server {
    listen 0.0.0.0:443 ssl default_server;
    …

    ssl_certificate      /etc/nginx/server.pem;
    ssl_certificate_key  /etc/nginx/server.key;
    …
}

If the existing files were replaced under the same name, no change is required. If the new files were stored under a different name or in a different location, the path to the left of the colon in the Compose file is adjusted accordingly.

Restart the nginx container #

nginx only reads the certificate and the key at startup. The container is therefore restarted in the /opt/relution directory:

cd /opt/relution
sudo docker compose restart nginx

If the Compose file was changed, a restart is not sufficient; instead, the container is recreated with the changed configuration:

sudo docker compose up -d nginx

If nginx does not start, the container logs show the cause, for example a faulty certificate file or a key that does not match:

sudo docker compose logs nginx

In this case, the backed-up files server.pem.old and server.key.old can be copied back until the error is resolved.

Finally, the Relution web interface is opened in the browser and the padlock icon in the address bar is used to check whether the new certificate with the new expiry date is delivered. Whether the complete chain is delivered can additionally be checked, for example, with WhatsMyChainCert →.