Deploy your applications with Traefik on a VPS

Why put Traefik in front of your VPS?

What Traefik brings concretely on a VPS

• Automatic discovery of Docker containers via the Docker provider (routes appear without a restart)
• Let's Encrypt SSL certificates generated and renewed automatically (HTTP-01, TLS-ALPN-01 or DNS-01 challenges), renewed by default 30 days before they expire
• Routing by domain, by path or by header, managed entirely through Docker labels
• Built-in web dashboard to visualize routers, services and middlewares in real time
• Ready-to-use middlewares: HTTPS redirection, basic auth, rate limiting, security headers, compression
• Automatic load balancing when you scale a service to several replicas
• HTTP/3 (QUIC) enabled on an entrypoint with a single option
• Providers other than Docker (Swarm, Kubernetes, Nomad, files) if your infrastructure grows

Prerequisites

Deploy Traefik with Docker Compose

1. 01

   Create the network and the directory structure

   Create a shared Docker network that Traefik and your applications will use, then a dedicated folder containing the acme.json file (the storage for certificates and their private keys):

   docker network create proxy
   mkdir -p /opt/traefik && cd /opt/traefik
   touch acme.json && chmod 600 acme.json

   Create the file before the first start: if the mounted path does not exist, Docker creates a directory in its place and Traefik can no longer write to it. The 600 permissions are mandatory: Traefik refuses a file readable by other users.

2. 02

   Configure the entrypoints and the ACME resolver

   Place this file in /opt/traefik/docker-compose.yml. It declares two entrypoints (web on :80, websecure on :443), a Let's Encrypt certificateResolver validated through the HTTP challenge, container discovery through the Docker socket mounted read-only, and the dashboard:

   services:
     traefik:
       image: traefik:v3.7
       container_name: traefik
       restart: unless-stopped
       ports:
         - "80:80"
         - "443:443"
         - "443:443/udp"
       command:
         - "--providers.docker=true"
         - "--providers.docker.exposedbydefault=false"
         - "--providers.docker.network=proxy"
         - "--entrypoints.web.address=:80"
         - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
         - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
         - "--entrypoints.websecure.address=:443"
         - "--entrypoints.websecure.http3=true"
         - "[email protected]"
         - "--certificatesresolvers.letsencrypt.acme.storage=/acme.json"
         - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web"
         - "--api.dashboard=true"
       volumes:
         - "/var/run/docker.sock:/var/run/docker.sock:ro"
         - "./acme.json:/acme.json"
       networks:
         - proxy
       labels:
         - "traefik.enable=true"
         - "traefik.http.routers.dashboard.rule=Host(`traefik.example.com`)"
         - "traefik.http.routers.dashboard.entrypoints=websecure"
         - "traefik.http.routers.dashboard.tls.certresolver=letsencrypt"
         - "traefik.http.routers.dashboard.service=api@internal"
         - "traefik.http.routers.dashboard.middlewares=dashboard-auth"
         - "traefik.http.middlewares.dashboard-auth.basicauth.users=admin:$$2y$$05$$REMPLACER_PAR_LE_HASH"
   
   networks:
     proxy:
       external: true

   The exposedbydefault=false option is essential: without it, every container on the VPS would be published, including your database. Pin the branch (v3.7) rather than latest, and follow the releases before moving to a new minor version.

3. 03

   Force the HTTP to HTTPS redirection

   The redirection is declared directly on the web entrypoint, with the two options --entrypoints.web.http.redirections.entrypoint.to=websecure and ...entrypoint.scheme=https already present in the file above. It is simpler and safer than a catch-all router with a middleware: all cleartext traffic is switched to HTTPS by a permanent redirect, with no label to repeat on each service, and the Let's Encrypt HTTP challenge still goes through on port 80.

4. 04

   Secure the dashboard

   The dashboard is exposed on traefik.example.com, behind the basicauth middleware named dashboard-auth. Generate a bcrypt hash (the apache2-utils package on Debian/Ubuntu) while doubling the $ signs, as a label value in a Compose file requires:

   apt install -y apache2-utils
   htpasswd -nB admin | sed -e 's/\$/\$\$/g'

   Paste the result in place of admin:$$2y$$05$$REMPLACER_PAR_LE_HASH. A hash pasted with single $ signs is read by Compose as variables and breaks authentication. Never leave the --api.insecure=true flag in production: it publishes the dashboard without authentication.

5. 05

   Launch Traefik

   Start the stack and follow the logs:

   cd /opt/traefik
   docker compose up -d
   docker compose logs -f traefik

   You should see the Docker provider start, then the dashboard router attach, with no ACME error. During your tests, temporarily add --certificatesresolvers.letsencrypt.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory: the Let's Encrypt staging server issues certificates that browsers do not trust, but it protects you from the production rate limit if a configuration keeps failing. Remove the option and empty acme.json before going to production.

6. 06

   Connect an application

   Each application lives in its own docker-compose.yml, attached to the proxy network and described by its labels:

   services:
     app:
       image: ghcr.io/example/app:1.0.0
       restart: unless-stopped
       networks:
         - proxy
       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.services.app.loadbalancer.server.port=3000"
   
   networks:
     proxy:
       external: true

   On docker compose up -d, Traefik detects the container, obtains the certificate and activates the route within seconds, without touching its own configuration. The loadbalancer.server.port label gives the application's internal port; it becomes mandatory as soon as the image exposes several. The router name (app here) must be unique across the whole VPS.

7. 07

   Check the certificate and the redirection

   Check from a machine outside the VPS:

   curl -I http://app.example.com
   curl -I https://app.example.com
   dig +short app.example.com

   The first request must return a permanent redirect to https://, the second a 200 (or your application's code) served with a valid Let's Encrypt certificate, and dig must show the VPS IP. The dashboard also lists each router with its certificate resolver. A port 80 that refuses the connection almost always points to the firewall.

Useful middlewares in production

Five middlewares to know

• BasicAuth on an admin tool (Adminer, Flower…): traefik.http.middlewares.adminauth.basicauth.users=admin:$$2y$$05$$..., then traefik.http.routers.myadmin.middlewares=adminauth. Same doubled-$ rule as for the dashboard.
• Rate limit in front of an API or a form: traefik.http.middlewares.ratelimit.ratelimit.average=100, ...ratelimit.period=1s and ...ratelimit.burst=200 allow 100 requests per second on average, with bursts up to 200. Without average, the limit is disabled.
• Security headers: the headers middleware sets HSTS (stsSeconds=31536000, stsIncludeSubdomains=true), X-Frame-Options: DENY (frameDeny=true) and X-Content-Type-Options: nosniff (contentTypeNosniff=true), with no separate configuration file.
• Redirect www to the bare domain: redirectregex with regex=^https://www\.(.+), replacement=https://$${1} and permanent=true. Remember to declare both hosts in the router rule so that the certificate covers www.
• Compression: traefik.http.middlewares.compress.compress=true enables gzip, Brotli and Zstandard depending on what the browser accepts, with no setting on the application side.

Enable HTTP/3 (QUIC)

Coming from Traefik v2: what breaks

v3 breaking changes

• Swarm: the Docker provider's swarmMode option no longer exists and blocks startup. Docker Swarm now has its own provider (--providers.swarm).
• Routing rules: Headers and HeadersRegexp become Header and HeaderRegexp, HostHeader disappears in favor of Host, and most matchers now accept a single value.
• Paths: Path and PathPrefix no longer read a regular expression or a placeholder such as {id}; such a route no longer matches anything. Switch to PathRegexp, which follows Go regexp syntax, like HostRegexp.
• Renamed or trimmed middlewares: IPWhiteList becomes IPAllowList (same options); the headers middleware loses sslRedirect, sslTemporaryRedirect, sslHost, sslForceHost and featurePolicy.
• Content-Type: Traefik no longer guesses the type of a response the backend did not type; add the ContentType middleware if an application relies on it.
• Removed providers and observability: Marathon, Rancher v1, Traefik Pilot and InfluxDB v1 metrics prevent startup; tracing goes through OpenTelemetry only (no more direct export to Jaeger, Zipkin or Datadog).

Traefik v3, Nginx or Caddy in front of your containers

Scroll the table

Troubleshooting: the most frequent errors

Symptoms and fixes

• Certificate not obtained, ACME unauthorized or 403 error in the logs: Let's Encrypt cannot reach your domain. Check from the outside that port 80 answers (curl -I http://app.example.com) and that DNS points to the VPS (dig +short app.example.com). Behind a CDN in proxy mode, prefer the dnsChallenge.
• permissions 644 for /acme.json are too open, please use 600: the resolver refuses the file. Fix it with chmod 600 /opt/traefik/acme.json then restart Traefik; this check protects the private keys stored inside.
• Route visible in the dashboard but 502 Bad Gateway: the container is not on the proxy network, or the internal port is wrong. Check with docker inspect <container> (Networks section), add the network or the loadbalancer.server.port label, then recreate the container. On a container attached to several networks, the traefik.docker.network=proxy label removes the ambiguity.
• Labels ignored, route missing from the dashboard: traefik.enable=true is missing (mandatory with exposedbydefault=false), or two services declare the same router name. Traefik's logs then report the conflict.
• BasicAuth refusing a correct password: the $ signs of the hash are not doubled in the docker-compose.yml. In a Compose file, each $ becomes $$; in a YAML or TOML dynamic configuration file, the hash is pasted as is.

Next step: harden the stack