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.
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
sudoand belongs to thedockergroup - 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:
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.comThe 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.
sudo install -d -o "$USER" -g "$USER" /opt/traefik /opt/traefik/letsencrypt
cd /opt/traefik
touch letsencrypt/acme.json
chmod 600 letsencrypt/acme.jsonThen create the Docker network shared between Traefik and the applications to publish:
docker network create proxyStep 3: Create the Dashboard Password
Install htpasswd, then generate the hash for the admin account. The command asks for the password twice:
sudo apt install -y apache2-utils
htpasswd -nB admin > /opt/traefik/dashboard.htpasswd
chmod 600 /opt/traefik/dashboard.htpasswdThe 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:
nano /opt/traefik/compose.yamlPaste this content, replacing the domain, the email address and YOUR_IP:
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:
cd /opt/traefik
docker compose config --quiet
docker compose up -d
docker compose psBoth services must be in the running state. Follow the startup in the logs, then exit with Ctrl+C:
docker compose logs -f traefikStep 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
proxynetwork, with noportssection. - 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:
sudo install -d -o "$USER" -g "$USER" /opt/whoami
nano /opt/whoami/compose.yamlservices:
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: trueStart it:
cd /opt/whoami
docker compose up -dTraefik 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:
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 -datesThe 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:
cd /opt/traefik
docker compose exec traefik wget -S -O- http://socket-proxy:2375/images/jsonThe 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:
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:8080Finally, 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:
cd /opt/traefik
htpasswd -nB admin > dashboard.htpasswd
docker compose restart traefikIf 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
- "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:
- "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:
cd /opt/traefik
docker compose pull
docker compose up -d
docker compose exec traefik traefik version
docker compose logs --tail 50 traefikThe 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 |
sudo tar -czf /root/traefik-$(date +%F).tar.gz -C /opt traefik
sudo chmod 600 /root/traefik-$(date +%F).tar.gzThis 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:
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 -dTroubleshooting
Start by checking the logs:
cd /opt/traefik
docker compose logs --tail 100 traefik
docker compose logs --tail 50 socket-proxyport is already allocated or address already in use
Another service is using port 80 or 443:
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:
chmod 600 /opt/traefik/letsencrypt/acme.json
cd /opt/traefik
docker compose restart traefikFailed 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
CONTAINERSis missing, Traefik receives403 Forbiddenwhen listing containers. - If the proxy is not allowed to open the socket, its publisher states that
privileged: truemay 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:
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:
cd /opt/traefik
docker compose exec traefik wget -qO- http://whoami:80The 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:
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:unauthorizedorconnection: 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:
- "--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:
cd /opt/traefik
docker compose logs --no-log-prefix traefik | grep 'dashboard@docker' | tail -n 5If 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:
cd /opt/traefik
docker compose down
sudo rmdir dashboard.htpasswd
htpasswd -nB admin > dashboard.htpasswd
chmod 600 dashboard.htpasswd
docker compose up -d