Learn Traefik - Let's Encrypt & ACME

#Introduction

Managing certificates manually — buying, placing, renewing before expiry — is the most boring and most disaster-prone job in the proxy world. Episode 15 removes all of that with ACME and Let's Encrypt: certificates are issued automatically, installed automatically, and renewed automatically without human intervention.

This is one of the biggest reasons people choose Traefik. After a one-time configuration, HTTPS across all your domains runs by itself. Let us understand the ACME protocol, how to configure a certificate resolver, the three challenge types, and how Traefik manages the certificate lifecycle.

#The ACME Protocol and Certificate Resolver

#How ACME Works

ACME (Automatic Certificate Management Environment) is the protocol for certificate automation. Traefik acts as an ACME client: it registers with Let's Encrypt, proves domain ownership through a challenge, then receives a certificate that is immediately installed. Certificates last 90 days and are automatically renewed around 30 days before expiry.

#Resolver Configuration

A certificate resolver is a static config block that connects Traefik to an ACME server:

certificatesResolvers:
  letsencrypt:
    acme:
      email: admin@example.com
      storage: /etc/traefik/acme.json
      httpChallenge:
        entryPoint: web

• email: the address for expiry and renewal notifications from Let's Encrypt.
• storage: the location of the acme.json file where all certificates and keys are stored.
• httpChallenge: proves domain ownership through the web entrypoint (port 80).

The acme.json file is a treasure trove: it contains the private keys of all certificates. Set strict permissions:

chmod 600 acme.json

#The Three Challenge Types

#HTTP-01

HTTP-01 is the simplest: Let's Encrypt asks for a random file at http://domain/.well-known/acme-challenge/<token>, and Traefik serves it. The requirement: port 80 must be open from the internet and requests must reach Traefik. This is why the web entrypoint in httpChallenge is mandatory.

#TLS-ALPN-01

TLS-ALPN-01 runs over port 443: Let's Encrypt contacts Traefik with the special acme-tls/1 ALPN, and Traefik proves domain ownership inside the TLS handshake. It does not require port 80, but needs port 443 open:

certificatesResolvers:
  letsencrypt:
    acme:
      email: admin@example.com
      storage: /etc/traefik/acme.json
      tlsChallenge: {}

#DNS-01

DNS-01 proves domain ownership through a DNS TXT record. This is the only way to get a wildcard certificate and requires no inbound ports at all. We dissect all its details in episode 16.

#Installing TLS on Routers

#Enabling HTTPS per Router

Certificates are issued for the domains a router requests. To enable TLS, the router must be on an HTTPS entrypoint and mention certResolver:

services:
  app:
    image: nginx:alpine
    labels:
      - traefik.enable=true
      - traefik.http.routers.app.rule=Host(`app.example.com`)
      - traefik.http.routers.app.entrypoints=websecure
      - traefik.http.routers.app.tls.certresolver=letsencrypt
      - traefik.http.routers.app.tls.domains[0].main=app.example.com
      - traefik.http.routers.app.tls.domains[0].sans=www.app.example.com
      - traefik.http.routers.app.service=app-svc
      - traefik.http.services.app-svc.loadbalancer.server.port=80

When this router appears, Traefik checks whether a certificate for app.example.com already exists in acme.json. If not, it immediately processes the challenge and issues one. The tls.domains[0].sans label registers additional SANs in a single certificate.

#The Certificate Lifecycle

#Renewal and Backup

Traefik monitors certificates and renews them automatically around 30 days before expiry, with several attempts if it fails. What you must do as an operator:

• Back up acme.json regularly — losing this file means losing the private keys.
• Never edit acme.json while Traefik is running; write through a backup-restore mechanism.
• Watch the logs for renewal errors — repeated failures mean a DNS or firewall problem.

For high availability with multiple Traefik instances, acme.json must be shared carefully — we cover the details in episode 26.

#Closing

Key takeaways:

• ACME automates certificate issuance and renewal.
• A certificate resolver needs an email, acme.json storage, and one challenge type.
• HTTP-01 needs port 80; TLS-ALPN-01 needs port 443; DNS-01 needs no inbound ports.
• Routers enable HTTPS with the tls.certresolver and tls.domains labels.
• Automatic renewal happens 30 days before expiry.
• Back up acme.json and test with a staging server before production.

In episode 16 next we will cover wildcard certificates & DNS challenge — certificates for all subdomains, DNS provider integrations like Cloudflare and Route53, env var configuration, multi-domain SANs, and troubleshooting DNS propagation and timeouts.