Custom Certificates in Traefik

For on-premise installations, VARIOS AI is served through Traefik. By default, Traefik requests the TLS certificate for your domain automatically from Let’s Encrypt (certificate resolver le). This requires your instance to be reachable from the internet on ports 80/443. In many enterprise environments this is undesirable or impossible. Instead of Let’s Encrypt, you can provide Traefik with your own certificate — for example a wildcard certificate, a certificate from your internal CA, or a commercially purchased certificate.

This page covers the certificate Traefik uses to secure incoming HTTPS connections from users. If VARIOS AI needs to reach outbound services that use self-signed certificates, you need a CA bundle inside the container instead — see Custom TLS Certificates.

Prerequisites

Certificate and private key in PEM format

Traefik needs two files: the certificate chain (.crt/.pem) and the private key (.key). Both must be in PEM format (a text file starting with -----BEGIN CERTIFICATE----- or -----BEGIN PRIVATE KEY-----).

Complete certificate chain

The certificate file must contain the server certificate and all intermediate certificates — the server certificate first, followed by the intermediates. Without the chain, browsers and API clients report a certificate error.

Unencrypted private key

Traefik cannot unlock passphrase-protected keys. The key must be stored without a passphrase.

Matching common name or SAN

The certificate must be issued for the domain configured as PROJECT_DOMAIN in your .env (or list it as a Subject Alternative Name).

Check format and validity up front:

openssl x509 -in varios.crt -noout -subject -issuer -dates -ext subjectAltName
openssl pkey -in varios.key -check -noout

Certificate and key belong together only if both checksums are identical:

openssl x509 -in varios.crt -noout -modulus | openssl md5
openssl pkey -in varios.key -noout -modulus | openssl md5

How Traefik obtains certificates

Traefik knows two ways to obtain a certificate for a router:

Method	Configuration	Use case
ACME / Let’s Encrypt	Label `traefik.http.routers.<name>.tls.certresolver=le` on the container	Default for instances reachable from the internet
File provider	YAML file in the `./traefik/dynamic` directory	Custom certificates, internal CA, wildcard certificates

The docker-compose.yml shipped for on-premise installations is already prepared for both. The Traefik service starts with the file provider enabled and mounts the required directories:

docker-compose.yml

traefik:
  image: traefik:v3.6
  command:
    [...]
    - "--providers.file.directory=/etc/traefik/dynamic"
    - "--providers.file.watch=true"
    [...]
  volumes:
    - "/var/run/docker.sock:/var/run/docker.sock:ro"
    - "./traefik/acme:/etc/traefik/acme"
    - "./traefik/dynamic:/etc/traefik/dynamic"
    - "./traefik/certs:/etc/traefik/certs"

So you do not need to modify the Traefik service. It is enough to place the certificate files, add a dynamic configuration, and disable the ACME resolver on the router.

Setup

Place the certificate files

Put the certificate and key into the traefik/certs directory next to your docker-compose.yml:

mkdir -p traefik/certs traefik/dynamic
cp /path/to/fullchain.pem traefik/certs/varios.crt
cp /path/to/privkey.pem   traefik/certs/varios.key

Protect the private key from unauthorized access:

chmod 644 traefik/certs/varios.crt
chmod 600 traefik/certs/varios.key

Never store private keys in a directory served by a web server, and never commit them to version control.

Create the dynamic configuration

Create the file traefik/dynamic/certificates.yml. Traefik picks it up automatically through the file provider — the paths refer to the paths inside the container (/etc/traefik/certs), not to host paths.

traefik/dynamic/certificates.yml

tls:
  certificates:
    - certFile: /etc/traefik/certs/varios.crt
      keyFile: /etc/traefik/certs/varios.key

  stores:
    default:
      defaultCertificate:
        certFile: /etc/traefik/certs/varios.crt
        keyFile: /etc/traefik/certs/varios.key

The certificates section makes the certificate available for matching hostnames. stores.default.defaultCertificate additionally sets it as the default certificate — that way Traefik also answers requests without a matching hostname with your certificate instead of the generated placeholder TRAEFIK DEFAULT CERT.

Disable Let's Encrypt on the router

In docker-compose.yml, remove the certificate resolver label from the php service. Keep the tls=true label — only the automatic issuance goes away:

docker-compose.yml

php:
  [...]
  labels:
    - "traefik.enable=true"
    # removed: traefik.http.routers.${STACKNAME}.tls.certresolver=le
    - "traefik.http.routers.${STACKNAME}.tls=true"
    - "traefik.http.routers.${STACKNAME}.rule=Host(`${PROJECT_DOMAIN}`)"
    - "traefik.http.routers.${STACKNAME}.entrypoints=websecure"
    - "traefik.http.services.${STACKNAME}.loadbalancer.server.port=80"
    - "traefik.http.routers.http-${STACKNAME}.middlewares=redirect-https"
    - "traefik.http.routers.http-${STACKNAME}.rule=Host(`${PROJECT_DOMAIN}`)"
    - "traefik.http.routers.http-${STACKNAME}.entrypoints=web"
    - "traefik.http.middlewares.redirect-https.redirectscheme.scheme=https"
    - "traefik.http.middlewares.redirect-https.redirectscheme.permanent=true"

If certresolver=le stays in place, Traefik keeps trying to issue a Let’s Encrypt certificate. In isolated networks this fails permanently and floods the log with ACME errors.

Optionally, you can also remove the ACME options from the Traefik service’s command block (--certificatesresolvers.le.*) if Let’s Encrypt is no longer used at all.

Apply the changes

docker compose up -d

The label change only takes effect once the container is recreated; docker compose up -d handles that automatically. Changes to files below traefik/dynamic and traefik/certs, on the other hand, are picked up without a restart thanks to --providers.file.watch=true.

Verification

After startup, check which certificate Traefik serves:

openssl s_client -connect chat.example.com:443 -servername chat.example.com </dev/null 2>/dev/null \
  | openssl x509 -noout -subject -issuer -dates

The output must show the issuer and validity of your certificate. If TRAEFIK DEFAULT CERT appears instead, the dynamic configuration was not loaded.

Check the certificate chain with:

curl -vI https://chat.example.com 2>&1 | grep -E "issuer|subject|SSL certificate"

Traefik logs errors while loading the dynamic configuration to the container log:

docker compose logs traefik | tail -50

Renewing the certificate

To replace an expiring certificate, simply swap the two files:

cp /path/to/new-fullchain.pem traefik/certs/varios.crt
cp /path/to/new-privkey.pem   traefik/certs/varios.key
chmod 600 traefik/certs/varios.key

Thanks to --providers.file.watch=true, Traefik usually detects the change automatically. If the old certificate is still served, force a reload:

docker compose restart traefik

Set a reminder ahead of the expiry date. Unlike Let’s Encrypt, a manually provided certificate does not renew itself.

Multiple domains

If VARIOS AI should be reachable under several hostnames, add more entries under certificates. Traefik selects the matching certificate based on the hostname sent via SNI:

traefik/dynamic/certificates.yml

tls:
  certificates:
    - certFile: /etc/traefik/certs/chat.crt
      keyFile: /etc/traefik/certs/chat.key
    - certFile: /etc/traefik/certs/ki.crt
      keyFile: /etc/traefik/certs/ki.key

  stores:
    default:
      defaultCertificate:
        certFile: /etc/traefik/certs/chat.crt
        keyFile: /etc/traefik/certs/chat.key

The additional hostnames must also appear in the router rule:

docker-compose.yml

- "traefik.http.routers.${STACKNAME}.rule=Host(`chat.example.com`) || Host(`ki.example.com`)"

A wildcard certificate (*.example.com) needs no special handling — it is configured like any other certificate and applies to all matching hostnames.

Hardening TLS options

The file provider also lets you define the permitted TLS versions and cipher suites. Add another file in the same directory:

traefik/dynamic/options.yml

tls:
  options:
    default:
      minVersion: VersionTLS12
      sniStrict: true
      cipherSuites:
        - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305
        - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305

The default option automatically applies to every router that has no TLS option of its own. sniStrict: true rejects connections without a matching hostname — verify beforehand that all clients and monitoring systems use SNI. The cipher suite list only affects TLS 1.2; the TLS 1.3 suites are fixed.

Troubleshooting

Symptom	Cause	Resolution
Browser shows `TRAEFIK DEFAULT CERT`	Dynamic configuration not loaded	Check the `.yml` file extension and the `traefik/dynamic` location, review the Traefik log
`unable to generate TLS certificate` in the log	ACME resolver still active	Remove the `tls.certresolver=le` label from the `php` service
`tls: private key does not match public key`	Certificate and key do not belong together	Compare the modulus checksums of both files (see Prerequisites)
Certificate warning despite a valid certificate	Intermediate certificates missing	Concatenate server certificate and intermediates into one file: `cat server.crt intermediate.crt > varios.crt`
`permission denied` when reading the key	File permissions too restrictive for the container	Check the file owner; Traefik runs as root inside the container and must be able to read the key
Change has no effect	Label change without recreating the container	Run `docker compose up -d` (not just `restart`)

Getting Started

Usage

Administration

Security

Changelog

Custom Certificates in Traefik

Prerequisites

How Traefik obtains certificates

Setup

Verification

Renewing the certificate

Multiple domains

Hardening TLS options

Troubleshooting

​Prerequisites

​How Traefik obtains certificates

​Setup

​Verification

​Renewing the certificate

​Multiple domains

​Hardening TLS options

​Troubleshooting

Prerequisites

How Traefik obtains certificates

Setup

Verification

Renewing the certificate

Multiple domains

Hardening TLS options

Troubleshooting