Skip to main content
Version: Edge

Note about TLS certificates

The eLabFTW container can run an HTTP or HTTPS server. Both will run internally on port 8080. This page describes several options you can choose regarding TLS configuration.

Option A: HTTP mode with a reverse proxy (Apache, nginx, HAProxy, traefik, ...)​

You can run the container in HTTP mode only if you have a reverse proxy in front doing TLS termination and sending the X-Forwarded-Proto header.

  • Set DISABLE_HTTPS=true

Reverse proxy configuration examples can be found here: https://github.com/elabftw/elabftw/tree/master/documentation/config_examples/.

Option B: HTTPS mode with Let's Encrypt certificates​

In order to request Let's Encrypt certificates, you need to install certbot and have your server publicly accessible. See the official Let's Encrypt documentation for your system: https://letsencrypt.org/getting-started/.

When requesting a new certificate, make sure that port 80 is open (and also port 443 for eLabFTW if it is the one you want to use). Once certbot is installed, the command to use might look like this:

certbot certonly --standalone -d elab.example.org

  • Set DISABLE_HTTPS=false
  • Set TLS_CERT_PATH=/etc/letsencrypt/live/<YOUR-DOMAIN>/fullchain.pem
  • Set TLS_KEY_PATH=/etc/letsencrypt/live/<YOUR-DOMAIN>/privkey.pem

We need to bind-mount live and archive dirs because certs are symlinks.

In volumes: section:

  • /etc/letsencrypt/live/<YOUR-DOMAIN>:/etc/letsencrypt/live/<YOUR-DOMAIN>:ro
  • /etc/letsencrypt/archive/<YOUR-DOMAIN>:/etc/letsencrypt/archive/<YOUR-DOMAIN>:ro

The user running the container (elabftw-worker) must have read access to the files.

Option C: HTTPS mode with custom certificates​

The webserver in the container expects TLS certificates to be in a particular order and format. Make sure that your certificate file contains certificates in this order: <certificate> <intermediate ca> <root ca>, with PEM encoding.

  • Set DISABLE_HTTPS=false
  • Set TLS_CERT_PATH=/etc/elabftw/certs/name-of-your-cert.pem
  • Set TLS_KEY_PATH=/etc/elabftw/certs/name-of-your-key.pem
  • Bind-mount /path/to/your/certs to /etc/elabftw/certs. So in the volumes: section it should look like: - /etc/my-certs-for-tls/elabftw:/etc/elabftw/certs:ro

The user running the container (elabftw-worker) must have read access to the files.

Option D: HTTPS mode with self-signed certificate​

warning

Only use this for testing purposes!

The container can generate its own self-signed certificate. This certificate will not be trusted and users will see a warning that they'll need to ignore. Do not use this option.

  • Set DISABLE_HTTPS=false.
  • Set GENERATE_TLS_CERT=true.

Configure TLS certificate renewal​

If you used Option A, B or C (meaning you have previously configured a TLS certificate) and are unfamiliar with the TLS certificate renewal procedure, follow the instructions below.

You need to configure a recurring task to renew the certificate, so that it does not expire and lock users out.

This section will only describe how to renew certificates generated via Let's Encrypt, as this will be the most likely case. Let's Encrypt certificates are valid only for a short period, and renewal must be automated (learn more here).

You will find the documentation for renewal with certbot here: certbot renew certificates.

Example if you use the container in HTTPS mode (with certificates mounted in the container, Options B or C).

/usr/local/bin/elabftw-renew-cert.sh
certbot renew --post-hook "docker exec elabftw reload nginx"

In the example above, we reload the nginx service in the container so the new certificate is picked up by the webserver.

If you used Option A, you might need to reload your reverse proxy, and there is no need to reload eLabFTW's webserver. Example with Apache:

/usr/local/bin/elabftw-renew-cert.sh
certbot renew --post-hook "systemctl restart apache2"

You then need to execute this daily with a cronjob or a systemd timer.

Example cronjob to execute at 03:12 every day:

12 3 * * * /usr/local/bin/elabftw-renew-cert.sh

If you're encountering issues, or if something is not clear, do not hesitate to join the eLabFTW chat room to find help: gitter chat (matrix room).