Traefik v3 on VPS: Docker Reverse Proxy with Automatic HTTPS

Why Traefik v3 over nginx for your Docker stack

• Automatic container discovery via Docker labels — no manual reload when you add a service.
• Automatic HTTPS with Let's Encrypt (TLS-ALPN-01 or HTTP-01 challenge): certificates obtained, stored and renewed without intervention.
• Native middlewares declarable by label: BasicAuth, rate-limit, security headers, redirects — no nginx module to write.
• Built-in real-time dashboard: view all routes, middlewares and certificate status from a browser.
• HTTP/3 (QUIC) support in a single config line: improves performance on high-latency connections.
• Routing by Host, PathPrefix, Headers or any combination — rules are written in expressive Go template syntax.
• Internal REST API: query router state, inspect active backends, automate CI/CD integrations.
• Compatible with Docker Swarm, Kubernetes and Nomad — migrate without changing your labels.

Technical prerequisites before you start

Complete Traefik v3 installation step by step

1. 01

   Create the shared Docker network. Traefik must be on the same network as the services it proxies. Create it once: docker network create traefik-public. This network will be referenced in every service docker-compose.yml.

2. 02

   Create the acme.json file for certificates. Let's Encrypt will write its certificates into this file. It must be owned by root with strictly 600 permissions: touch /opt/traefik/acme.json && chmod 600 /opt/traefik/acme.json. If permissions are wrong, Traefik will refuse to start.

3. 03

   Create the Traefik docker-compose.yml. Place this file at /opt/traefik/docker-compose.yml with the full configuration including TLS entrypoints, the Let's Encrypt ACME resolver, and the protected dashboard labels.

4. 04

   Generate the BasicAuth hash for the dashboard. Replace the hardcoded string with a real bcrypt hash: echo $(htpasswd -nB admin) | sed -e 's/\$/\$\$/g'. The htpasswd command is in the apache2-utils package on Debian/Ubuntu. Dollar signs must be doubled ($$) in Docker Compose label values.

5. 05

   Start Traefik. From /opt/traefik/: docker compose up -d. Check logs: docker compose logs -f traefik. You should see "Starting provider" providerType=Docker then "Attaching router" routerName=dashboard. An error on acme.json means wrong permissions.

6. 06

   Add a service behind Traefik. In your application's docker-compose.yml, join the traefik-public network (as external) and add the four key labels: traefik.enable=true, the Host() rule, the websecure entrypoint, the letsencrypt certresolver, and the backend port. Traefik detects the container immediately after docker compose up -d.

7. 07

   Verify Let's Encrypt certificates. Inspect acme.json: cat /opt/traefik/acme.json | python3 -m json.tool | grep -A3 'domain'. You should see your domains listed with an expiry 90 days out. Alternatively, the Traefik dashboard lists all active certificates under the *Routers* tab.

8. 08

   Validate the HTTP→HTTPS redirect. Test with curl: curl -v http://app.your-domain.com. You must receive a 301 Moved Permanently to https://. A connection refused on port 80 means firewall rules are blocking the port.

9. 09

   Enable HTTP/3 on the browser side. Add the Alt-Svc header via a global middleware in your Traefik labels or a static traefik.yml config file. The header Alt-Svc: h3=":443"; ma=86400 tells the browser your server supports QUIC. Verify with curl --http3 https://app.your-domain.com -v.

Essential middlewares: BasicAuth, rate-limit and security headers

• BasicAuth on a private route — to protect an admin tool (Adminer, Flower, etc.): add traefik.http.middlewares.adminauth.basicauth.users=admin:$$hash$$ and traefik.http.routers.myadmin.middlewares=adminauth labels on the service.
• Rate-limit against abuse — protects an API or contact form: set ratelimit.average=100 (100 req/s average) and ratelimit.burst=50 (burst of 50 tolerated), then apply the middleware on the router.
• HTTP security headers — X-Frame-Options, X-Content-Type-Options, Strict-Transport-Security: Traefik's headers middleware accepts all these values directly as labels, no separate nginx config file needed.
• Redirect Regex — to redirect www.your-domain.com to your-domain.com: use the redirectregex middleware with permanent=true and a regex ^https://www\.(.+) → https://${1}.
• Compress — enable gzip/brotli compression on all text responses with a single label: traefik.http.middlewares.compress.compress=true. Apply globally by adding it as a default middleware in the static configuration.

Migrating from Traefik v2: breaking changes

• docker.swarmMode renamed to docker.swarmmode (all lowercase). If your v2 config uses the old casing, Traefik v3 silently ignores it and Swarm discovery doesn't work.
• PathPrefix rule without trailing slash: in v3, PathPrefix('/api') is equivalent to PathPrefix('/api/') — the trailing slash is normalized. If you had rules that depended on this behavior to distinguish /api from /apiv2, revise them.
• tls.certificates in dynamic configuration: in v2, you could define manual certificates directly in a file provider's dynamic config. In v3, this section must be in the static configuration (traefik.yml) or via a dedicated provider.
• errors middleware: the query parameter is renamed to url. Any config using errors.query must be updated to errors.url.
• Removal of spiffe protocol support: if you used SPIFFE authentication in a Consul infrastructure, migrate to a standard mTLS solution before upgrading to v3.
• Docker constraints configuration: the constraints syntax has changed to align with the standard Docker tag format. Check your constraint list if you were filtering services by tag.

Traefik v3 vs nginx vs Caddy: which reverse proxy for Docker?

Scroll the table

Troubleshooting: the five most common errors

• level=error msg="Unable to obtain ACME certificate" error="acme: error 403" or unauthorized — Let's Encrypt can't verify your domain. Check that port 80 is open from the Internet and that your domain's DNS points to your VPS IP.
• level=error msg="The acme.json file has bad file permissions" then Traefik refuses to start — file permissions are not 600. Fix: chmod 600 /opt/traefik/acme.json. This check is intentionally blocking: a world-readable file would expose your private keys.
• Service visible in Traefik dashboard but 502 Bad Gateway — the service container is not on the traefik-public network. Check with docker inspect <container> | grep -A20 Networks. Add the network in the service's docker-compose.yml and recreate the container.
• Labels silently ignored, route absent from dashboard — you forgot traefik.enable=true on the service, or --providers.docker.exposedbydefault=false is active (recommended) and the label is missing. Also check that the router name in traefik.http.routers.<name>.rule is unique across all your services.
• invalid character '$' in label value — dollar signs in BasicAuth hashes are not doubled in the Compose file. The correct syntax is $$2y$$10$$... (each $ becomes $$) when the value is in a docker-compose.yml. If you pass the value via an environment variable, a single $ is enough.

Next step: harden your Docker stack for production