EN

Applications

Traefik as a Reverse Proxy with Docker

Deploy Traefik with Docker Compose on Debian or Ubuntu: automatic HTTPS with Let's Encrypt, publishing by labels, a protected dashboard, updates and backup.

10 min read, updated on 18 November 2026

On this page

Your values

Enter them once and the commands in this guide update.

This guide explains how to place Traefik in front of your Docker containers. Traefik receives visitors on ports 80 and 443, obtains and renews Let's Encrypt certificates, then forwards each request to the right container based on its labels.

By the end of the guide, a test application answers on https://app.your-domain.com. The Traefik dashboard is available at https://traefik.your-domain.com, only from your IP address and with a password. You will also know how to update and back up the installation.

The versions shown are the latest stable releases at the time of writing, in November 2026: Traefik v3.7.19 and whoami v1.12.0.

Order a Server

This guide applies to servers that you administer yourself:

Prerequisites

  • A server running Debian 12 or 13, or Ubuntu 22.04 or 24.04
  • SSH access with a user that has sudo and belongs to the docker group
  • Docker Engine and Docker Compose, installed with the guide Install Docker Engine and Docker Compose
  • A domain name whose DNS zone you manage
  • No other software on ports 80 and 443, such as Nginx, Apache, Caddy or Nginx Proxy Manager
  • A fixed IP address on your computer to reach the dashboard, or a VPN

Ports Used

Port Direction Purpose To open
80/tcp Inbound HTTP-01 validation and redirect to HTTPS Yes
443/tcp Inbound HTTPS sites and dashboard Yes
8080/tcp None Traefik's insecure API, disabled here No
2375/tcp Internal Docker network Docker socket proxy, never published on the server No

Step 1: Point the Names to the Server

Create two A records pointing to YOUR_SERVER_IP: app.your-domain.com and traefik.your-domain.com. If your domain is managed at HostMyServers, follow the guide Create an A record.

Then check the result from the server:

Terminal
sudo apt update
sudo apt install -y bind9-dnsutils
dig +short A app.your-domain.com
dig +short A traefik.your-domain.com
dig +short AAAA traefik.your-domain.com

The first two commands must return your server's address. The last one must stay empty: the dashboard is filtered by IPv4 address, and an IPv6 connection would be refused.

Step 2: Prepare the Folders and the Network

Create the project folder and the file that will hold the certificates. Traefik rejects this file if users other than its owner can read it.

Terminal
sudo install -d -o "$USER" -g "$USER" /opt/traefik /opt/traefik/letsencrypt
cd /opt/traefik
touch letsencrypt/acme.json
chmod 600 letsencrypt/acme.json

Then create the Docker network shared between Traefik and the applications to publish:

Terminal
docker network create proxy

Step 3: Create the Dashboard Password

Install htpasswd, then generate the hash for the admin account. The command asks for the password twice:

Terminal
sudo apt install -y apache2-utils
htpasswd -nB admin > /opt/traefik/dashboard.htpasswd
chmod 600 /opt/traefik/dashboard.htpasswd

The file contains a bcrypt hash, not the plain-text password. Keeping it in a file means you don't have to double the $ characters in Docker Compose labels.

Step 4: Write the Compose File

Create the file:

Terminal
nano /opt/traefik/compose.yaml

Paste this content, replacing the domain, the email address and YOUR_IP:

YAML
services:
  socket-proxy:
    image: tecnativa/docker-socket-proxy:3.4
    container_name: traefik-socket-proxy
    restart: unless-stopped
    environment:
      CONTAINERS: "1"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - socket

  traefik:
    image: traefik:v3.7.19
    container_name: traefik
    restart: unless-stopped
    depends_on:
      - socket-proxy
    security_opt:
      - no-new-privileges:true
    ports:
      - "80:80"
      - "443:443"
    command:
      - "--entrypoints.web.address=:80"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--entrypoints.web.http.redirections.entrypoint.permanent=true"
      - "--entrypoints.websecure.address=:443"
      - "--entrypoints.websecure.http.tls=true"
      - "--entrypoints.websecure.http.tls.certresolver=le"
      - "--providers.docker=true"
      - "--providers.docker.endpoint=tcp://socket-proxy:2375"
      - "--providers.docker.exposedbydefault=false"
      - "--providers.docker.network=proxy"
      - "--api.dashboard=true"
      - "--api.insecure=false"
      - "--certificatesresolvers.le.acme.email=admin@your-domain.com"
      - "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"
      - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
      - "--log.level=INFO"
      - "--accesslog=true"
    volumes:
      - ./letsencrypt:/letsencrypt
      - ./dashboard.htpasswd:/etc/traefik/dashboard.htpasswd:ro
    networks:
      - proxy
      - socket
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.dashboard.rule=Host(`traefik.your-domain.com`)"
      - "traefik.http.routers.dashboard.entrypoints=websecure"
      - "traefik.http.routers.dashboard.service=api@internal"
      - "traefik.http.routers.dashboard.middlewares=dashboard-ip,dashboard-auth"
      - "traefik.http.middlewares.dashboard-ip.ipallowlist.sourcerange=YOUR_IP/32"
      - "traefik.http.middlewares.dashboard-auth.basicauth.usersfile=/etc/traefik/dashboard.htpasswd"

networks:
  proxy:
    external: true
  socket:
    internal: true
Element Purpose
socket-proxy Filters access to the Docker API: Traefik can read containers, but neither create nor modify them
CONTAINERS: "1" Allows reading containers, while write requests stay blocked by default
socket Internal network with no Internet access, reserved for Traefik and the proxy
exposedbydefault=false Only containers carrying traefik.enable=true are published
network=proxy Traefik reaches the applications through this network
httpchallenge Let's Encrypt validates each name on port 80
certresolver=le Every site on the HTTPS entrypoint receives a certificate
api@internal Internal service that provides the dashboard
dashboard-ip then dashboard-auth Filters the IP address, then asks for the password

Traefik does not mount the Docker socket directly: if the container exposed to the Internet were compromised, the attacker would not gain control of Docker. This is one of the protections recommended by Traefik's documentation.

Step 5: Start Traefik

Validate the file, then start the containers:

Terminal
cd /opt/traefik
docker compose config --quiet
docker compose up -d
docker compose ps

Both services must be in the running state. Follow the startup in the logs, then exit with Ctrl+C:

Terminal
docker compose logs -f traefik

Step 6: Check the Firewall

Docker publishes ports 80 and 443 with its own rules, applied before those of UFW. These two ports are therefore reachable even without ufw allow, and UFW cannot restrict them. The guide Configure the UFW Firewall explains how this works.

Two rules follow from this:

  • Do not publish your applications' ports: they stay on the proxy network, with no ports section.
  • If you use your instance's built-in firewall, also allow ports 80 and 443 from your client area.

Step 7: Publish an Application

Create a test application in its own folder:

Terminal
sudo install -d -o "$USER" -g "$USER" /opt/whoami
nano /opt/whoami/compose.yaml
YAML
services:
  whoami:
    image: traefik/whoami:v1.12.0
    restart: unless-stopped
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.whoami.rule=Host(`app.your-domain.com`)"
      - "traefik.http.routers.whoami.entrypoints=websecure"
      - "traefik.http.services.whoami.loadbalancer.server.port=80"

networks:
  proxy:
    external: true

Start it:

Terminal
cd /opt/whoami
docker compose up -d

Traefik detects the container on its own, without a restart. The loadbalancer.server.port label gives the listening port inside the container. For your own applications, reuse these four labels, changing the router name, the domain and the port.

Check the Result

Test both protocols, then check the certificate:

Terminal
curl -I http://app.your-domain.com
curl -I https://app.your-domain.com
echo | openssl s_client -connect app.your-domain.com:443 -servername app.your-domain.com 2>/dev/null | openssl x509 -noout -issuer -dates

The HTTP request must return a 308 redirect to HTTPS, and the HTTPS request a 200 code. The certificate issuer must be Let's Encrypt. The first certificate may take a few moments.

Then check that the socket proxy blocks what is not allowed:

Terminal
cd /opt/traefik
docker compose exec traefik wget -S -O- http://socket-proxy:2375/images/json

The expected response is 403 Forbidden.

From your computer, test the dashboard. The first call must return 401, the second the Traefik version, and the third must not respond:

Terminal
curl -I https://traefik.your-domain.com/dashboard/
curl -u admin https://traefik.your-domain.com/api/version
curl -m 5 http://YOUR_SERVER_IP:8080

Finally, open https://traefik.your-domain.com/dashboard/ in your browser. The trailing slash is required. From another IP address, the same page must return 403.

Manage Dashboard Access

To change the password, regenerate the file, then restart Traefik:

Terminal
cd /opt/traefik
htpasswd -nB admin > dashboard.htpasswd
docker compose restart traefik

If your IP address changes, edit the dashboard-ip label in compose.yaml, then run docker compose up -d. If it changes often, reserve the dashboard for a private network instead, using WireGuard or Tailscale.

Common Settings

Answer on Several Names

YAML
- "traefik.http.routers.whoami.rule=Host(`app.your-domain.com`) || Host(`www.your-domain.com`)"

Each name must point to the server for the certificate to be issued.

Protect an Application with the Same Rules

Middlewares declared on the Traefik container can be reused by other containers, with the @docker suffix:

YAML
- "traefik.http.routers.whoami.middlewares=dashboard-ip@docker,dashboard-auth@docker"

Update

First read the release notes and, for a minor or major version change, the migration guide. Then back up the installation, change the traefik:v3.7.19 tag in compose.yaml, and run:

Terminal
cd /opt/traefik
docker compose pull
docker compose up -d
docker compose exec traefik traefik version
docker compose logs --tail 50 traefik

The tecnativa/docker-socket-proxy:3.4 image stays on the HAProxy 3.4 branch and its publisher rebuilds it every week: docker compose pull fetches these updates. Do the same in /opt/whoami and in your applications' folders.

Back Up and Restore

The /opt/traefik folder contains everything you need to keep:

Path Contents
compose.yaml Configuration of Traefik and the socket proxy
dashboard.htpasswd Hash of the dashboard password
letsencrypt/acme.json Certificates, private keys and ACME account
Terminal
sudo tar -czf /root/traefik-$(date +%F).tar.gz -C /opt traefik
sudo chmod 600 /root/traefik-$(date +%F).tar.gz

This archive contains private keys: copy it off the server to an encrypted location. Also back up your Compose files and your applications' data.

To restore the archive, replacing YYYY-MM-DD with its date, create the network if it does not exist yet on this server:

Terminal
cd /opt/traefik 2>/dev/null && docker compose down
sudo tar -xzf /root/traefik-YYYY-MM-DD.tar.gz -C /opt
docker network create proxy
cd /opt/traefik
docker compose up -d

Troubleshooting

Start by checking the logs:

Terminal
cd /opt/traefik
docker compose logs --tail 100 traefik
docker compose logs --tail 50 socket-proxy

port is already allocated or address already in use

Another service is using port 80 or 443:

Terminal
sudo ss -ltnp | grep -E ':(80|443) '
docker ps --format '{{.Names}} {{.Ports}}'

Stop that service if it is no longer needed, for example with sudo systemctl disable --now nginx.

permissions 644 for /letsencrypt/acme.json are too open, please use 600

Fix the permissions, then restart Traefik:

Terminal
chmod 600 /opt/traefik/letsencrypt/acme.json
cd /opt/traefik
docker compose restart traefik

Failed to retrieve information of the docker client and server host

Traefik cannot reach the socket proxy. Check that socket-proxy is running and that both services share the socket network. Depending on the cause shown in its logs:

  • If the server has no IPv6 and the proxy does not start, add DISABLE_IPV6: "1" to its environment variables.
  • If CONTAINERS is missing, Traefik receives 403 Forbidden when listing containers.
  • If the proxy is not allowed to open the socket, its publisher states that privileged: true may be required with some SELinux or AppArmor profiles. Add this option only as a last resort.

404 page not found

No router matches the request. Check that the container is running, that it carries traefik.enable=true, that the name in Host() is exact, and that it is attached to the proxy network:

Terminal
docker network inspect proxy --format '{{range .Containers}}{{.Name}} {{end}}'

Bad Gateway or Gateway Timeout

Traefik finds the router but cannot reach the application. Check the port given in loadbalancer.server.port, then test from Traefik:

Terminal
cd /opt/traefik
docker compose exec traefik wget -qO- http://whoami:80

The application must listen on 0.0.0.0 inside its container. If it listens only on 127.0.0.1, Traefik cannot reach it.

The Browser Shows TRAEFIK DEFAULT CERT

Traefik does not have a valid certificate for this name yet and presents its default certificate. Look for the cause in the logs:

Terminal
cd /opt/traefik
docker compose logs traefik | grep -iE 'acme|certificate'

Unable to obtain ACME certificate for domains

The message contains the reason for the refusal:

  • urn:ietf:params:acme:error:dns: the name does not exist in DNS yet or has not propagated.
  • urn:ietf:params:acme:error:unauthorized or connection: Let's Encrypt cannot reach port 80. Check the A and AAAA records, then your instance's firewall. If everything is correct, contact support from your client area.
  • urn:ietf:params:acme:error:caa: a CAA record forbids Let's Encrypt.
  • urn:ietf:params:acme:error:rateLimited: too many requests were sent. Wait until the end of the period given.

For your tests, temporarily add the Let's Encrypt staging environment, whose certificates are not trusted by browsers:

YAML
- "--certificatesresolvers.le.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory"

Before going back to production, remove this line and empty acme.json with truncate -s 0 /opt/traefik/letsencrypt/acme.json, without changing its permissions. Then run docker compose up -d.

403 Forbidden on the Dashboard

Your IP address is not the one in the dashboard-ip label. The access log shows the address Traefik sees, at the start of the line:

Terminal
cd /opt/traefik
docker compose logs --no-log-prefix traefik | grep 'dashboard@docker' | tail -n 5

If this address belongs to a Docker gateway, the connection probably arrived over IPv6: delete the name's AAAA record.

is a directory for dashboard.htpasswd

The file did not exist at the first startup and Docker created a folder in its place. Delete it, recreate the file, then restart the container:

Terminal
cd /opt/traefik
docker compose down
sudo rmdir dashboard.htpasswd
htpasswd -nB admin > dashboard.htpasswd
chmod 600 dashboard.htpasswd
docker compose up -d

References