Skip to main content

TLS Certificates

Atrium requires HTTPS. The Traefik reverse proxy handles TLS termination and supports two certificate sources.

Option A: Let's Encrypt (default)​

By default, Traefik obtains a free TLS certificate from Let's Encrypt automatically using the HTTP-01 challenge:

  1. Traefik requests a certificate for your domain.
  2. Let's Encrypt verifies you control the domain by making an HTTP request to port 80.
  3. The certificate is issued and stored in /certs/acme.json inside the Traefik container.
  4. Certificates are renewed automatically before expiry (Let's Encrypt certificates are valid for 90 days).

Requirements:

  • Port 80 must be accessible from the internet (Let's Encrypt needs to reach it).
  • The domain's DNS must point to the server's IP.

DNS-01 challenge (alternative)​

If port 80 is blocked, Traefik can use the DNS-01 challenge instead. This verifies domain ownership via a DNS TXT record, which doesn't require inbound port 80 access.

To use DNS-01 with Cloudflare:

  1. Set CF_DNS_API_TOKEN in your .env file with a Cloudflare API token (Zone → DNS → Edit permissions).
  2. Update the Traefik configuration to use the dnsChallenge resolver instead of httpChallenge.

Other DNS providers are supported via Traefik's ACME provider plugins. See Traefik's ACME documentation for the full list.

Option B: Custom certificates​

If you have your own TLS certificates (e.g., from an internal CA or a purchased certificate), you can configure Traefik to use them directly:

  1. Place your certificate and private key on the server (e.g., /opt/atrium/certs/).
  2. Update the Traefik configuration to use file-based certificates instead of ACME.
  3. Mount the certificate directory into the Traefik container.

Ensure you handle certificate renewal yourself — Traefik won't renew custom certificates automatically.

Self-signed certificates (development only)​

For testing or development, you can use self-signed certificates. Browsers will show a security warning, but the system will function normally. Do not use self-signed certificates in production — pre-registration email links and kiosk PWA installations require a trusted certificate.