Set Up Traefik 3: Reverse Proxy with Docker, HTTPS and Authentication
Traefik 3 as a reverse proxy for Docker: prepare the server, set up a domain, automatic Let's Encrypt certificates, middlewares, basic auth and Google login. Step by step for beginners.

Contents
Traefik 3.7traefik-forward-auth 4.14Docker 29.9Docker Compose 5.7Ubuntu 24.04You have a server and want to run several services on it, say a document management system, a password manager and a website? Then you quickly hit a problem: every service wants to be reachable, but the server has one IP address and only two standard ports for websites, 80 and 443. The solution is called a reverse proxy.
In this post I set up a server from scratch and install Traefik version 3 on it. Traefik accepts all requests, fetches HTTPS certificates on its own and forwards each request to the right Docker container. New services later need only a few lines in their Docker Compose file, and you never have to restart Traefik. I ran every step on a fresh server with Ubuntu 24.04. The outputs and screenshots come from that test.
What you will learn in this post
- What a reverse proxy does and how Traefik is built (entrypoints, routers, middlewares, services)
- Setting up a server: updates, your own user, firewall, Docker
- Pointing a domain at the server with a wildcard record
- Running Traefik 3 with automatic HTTPS (Let’s Encrypt) and a protected dashboard
- Using middlewares: password protection, rate limit, security headers, compression, IP filter
- Connecting services via labels and finding errors
- Optional: wildcard certificate, Google login and a hardened Docker socket
You need a server (VPS) with Ubuntu, a domain and about two hours. You do not need any Docker experience. If terminal commands are still unfamiliar, read my Linux terminal guide first. How to choose and secure a server is covered in more detail in the VPS guide for beginners.
What is a reverse proxy and why Traefik?
Picture an office building with a reception desk. Visitors all come through the same door and say who they want to see. The person at the desk sends them to the right office. A reverse proxy does exactly that for your server:
┌─────────────────────────────┐
Browser ──► :443 ──► │ Traefik │ ──► paperless:8000
(HTTPS) │ paperless.domain.com │ ──► vault:80
│ vault.domain.com │ ──► blog:2368
└─────────────────────────────┘Without a reverse proxy you would have to run every service on its own port (123.45.67.89:9000), and every service would have to handle HTTPS itself. With a reverse proxy you reach everything through subdomains like paperless.domain.com, on the standard ports 80 (HTTP) and 443 (HTTPS). The proxy manages the certificates in one central place.
There are several good reverse proxies. This is how I see them:
| Proxy | Strength | Weakness |
|---|---|---|
| Nginx Proxy Manager | Web interface, very beginner-friendly | You click through every change by hand |
| Caddy | Very short configuration, HTTPS automatic | You have to enter Docker containers in the file yourself |
| Traefik | Finds Docker containers by itself and configures itself via labels | More terms, steeper learning curve |
I use Traefik here because I describe services directly in their own docker-compose file. If you start a new container with the right labels, Traefik detects it within a few seconds and creates the route and certificate.
The terms in Traefik
Traefik has a few terms of its own. Once you have understood them, every configuration becomes readable:
| Term | Meaning | Example in this guide |
|---|---|---|
| Entrypoint | A port Traefik listens on | http (80) and https (443) |
| Router | Rule that assigns a request to a service | Host(`whoami.domain.com`) |
| Middleware | Intermediate step that checks or changes the request | Password protection, rate limit |
| Service | The target the request finally goes to | Port 80 in the whoami container |
| Provider | Source Traefik reads its configuration from | Docker labels and files |
| Certificate resolver | Fetches and renews certificates | Let’s Encrypt |
A request always takes the same path:
Request ► Entrypoint ► Router ► Middlewares ► Service ► ContainerTraefik also distinguishes two kinds of configuration:
- Static configuration: Applies to Traefik itself (ports, certificates, providers). Traefik reads it only at startup. Changes need a restart. In our setup it lives in the file
traefik.yml. - Dynamic configuration: Describes routers, middlewares and services. Traefik reads it continuously and applies changes immediately. It comes from the labels of your Docker containers and from YAML files in the
rulesfolder.
Prepare the server
Which server should I choose?
For this guide I use a server that is not located at my home. That has the following advantages:
- Easier accessibility thanks to a fixed IPv4 address
- Fast internet connection
- Predictable costs
- No wear on my own hardware, no power costs and no noise at home
Of course there are drawbacks too, such as running costs and dependence on the provider. The guide works with any server that can run Docker. In the past I had problems with virtual servers that were virtualized with OpenVZ instead of KVM. For the test I used a cloud server at Hetzner with 2 vCPUs and 4 GB RAM. The VPS and root servers (dedicated CPU) from Netcup are also recommended. If you are not yet a customer there, these vouchers get you a discount. I receive a commission for referred new customers.
As the operating system I choose Ubuntu 24.04 LTS. Another one would work too, but I have a lot of experience with Ubuntu. Standard support runs until April 2029, so you will not need to move to the next version for a long time.
Connect to the server
Once the server is ready, you connect via SSH. On macOS and Linux the terminal is enough. On Windows you use Windows Terminal, PuTTY or a similar program. I use Windows Terminal.
ssh root@{{server_ip}}
The first time, SSH asks whether you trust the server. Answer yes and enter the password. The password is not displayed while you type. Afterwards the server greets you (the message can look slightly different depending on the provider):

Update the system
First we fetch all updates. apt update downloads the current package list, apt upgrade installs the new versions:
apt update
apt upgrade -yThe -y answers the confirmation question automatically with “yes”. If the kernel was updated, restart the server with reboot afterwards and connect again.
Server name and time zone
The server gets a name that you see in the command prompt. We also set the time zone so logs show the right time:
hostnamectl set-hostname meinserver
timedatectl set-timezone Europe/BerlinCheck the result with these commands:
hostnamectl | grep "Static hostname"
timedatectl | grep "Time zone" Static hostname: meinserver
Time zone: Europe/Berlin (CET, +0100)The time zone helps you later when you compare certificates and logs. timedatectl list-timezones lists all time zones.
Create your own user
With the user root you may do anything, including destroying the system. That is why we create a normal user who may run administrator commands only with a leading sudo (Superuser do).
adduser {{username}}
usermod -aG sudo {{username}}adduser asks for a password and a few optional details (name, phone) that you can skip with Enter. usermod -aG sudo adds the user to the group sudo. Here -a means “append” and -G means “group”. Without -a, the user would be removed from all other groups.
Check that everything worked:
id {{username}}uid=1000({{username}}) gid=1000({{username}}) groups=1000({{username}}),27(sudo),100(users)If you have been logging in with an SSH key so far, copy it into the new user’s home directory. Otherwise the server asks for the password at login:
rsync --archive --chown={{username}}:{{username}} ~/.ssh /home/{{username}}Now log out and log in again with the new user:
exit
ssh {{username}}@{{server_ip}}From now on you work as this user. All commands that need administrator rights start with sudo. What happens without sudo you can see with apt:
apt updateReading package lists... Done
E: Could not open lock file /var/lib/apt/lists/lock - open (13: Permission denied)
E: Unable to lock directory /var/lib/apt/lists/With sudo apt update it works. How to secure the server further (enforce SSH keys, disable root login) is covered in the VPS guide.
Set up the firewall
A firewall lets through only the connections you allow. Ubuntu ships ufw for this. We allow SSH (otherwise you lock yourself out!), HTTP and HTTPS:
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw statusufw enable warns you that existing SSH connections might be interrupted. Since we allowed SSH beforehand, confirm with y.
Status: active
To Action From
-- ------ ----
OpenSSH ALLOW Anywhere
80/tcp ALLOW Anywhere
443/tcp ALLOW Anywhere
OpenSSH (v6) ALLOW Anywhere (v6)
80/tcp (v6) ALLOW Anywhere (v6)
443/tcp (v6) ALLOW Anywhere (v6)Install Docker
Now comes the most important part: Docker and Docker Compose. We use Docker’s official package repository so you always get current versions:
sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-pluginDocker starts automatically with the system on Ubuntu. You can check it with sudo systemctl is-enabled docker; the answer is enabled.
So that you do not have to write sudo in front of every Docker command, add your user to the group docker:
sudo usermod -aG docker {{username}}The group change only applies after a new login. Log out, log in again and test the installation:
docker --version
docker compose version
docker run --rm hello-worldDocker version 29.9.3, build 5457199
Docker Compose version v5.7.0
Hello from Docker!
This message shows that your installation appears to be working correctly.Note: Docker Compose is built in as a plugin and is called docker compose (with a space). The former standalone program docker-compose (with a hyphen) is no longer developed. The files from this guide work with both.
Terminal basics for the next steps
We need a few commands all the time. If you already know them, skip this part. With cd (“change directory”) you change the folder; the tilde (~) stands for your home directory. mkdir creates a new folder, ls shows the contents.
cd ~
mkdir docker
lsWith ls -l you see permissions and owner, with ls -A also hidden files (everything that starts with a dot), and ls -Al combines both. With cd docker you enter the new folder, with cd .. you go back up.
You edit text with nano, a simple editor in the terminal. You save with Ctrl + O and Enter and quit with Ctrl + X. You can also edit files on your own computer and paste them into nano. Make sure the indentation is preserved, because YAML is sensitive to it.
The shell can also write text into files. You will need that later for passwords and keys. echo prints a text, > writes it into a file and overwrites it, >> appends it:
echo "hello" > test.txt
echo "goodbye" >> test.txt
cat test.txthello
goodbyecat prints the contents of a file. rm test.txt deletes the file again. A line that starts with a hash (#) is a comment. The shell and YAML files ignore it.
Two tips save a lot of typing: the Tab key completes commands and file names (type cd d and press Tab). The arrow keys ↑ and ↓ bring back earlier commands.
Set up a domain
The server has only one IP address, but we want to run several services. You could reach them via different ports (123.45.67.89:443, 123.45.67.89:9000), but that is hard to remember. And you do not get a trusted HTTPS certificate for a bare IP address. With a reverse proxy on ports 80 and 443, you get one subdomain per service instead: mail.domain.com for the mail client, blog.domain.com for the blog. Subdirectories like domain.com/blog would also be possible, but many applications cope badly with them. Subdomains are more reliable.
There are free domains, for example at DuckDNS, but they usually come with restrictions. Students often get a domain free for one year with the GitHub Student Developer Pack. Buying your own domain is not expensive, though. At Netcup a .de domain costs around €5 a year permanently. Any other provider works too, as long as you can set DNS records yourself. Watch out: some providers charge much more from the second year on, especially if the first year costs only €1.
Set DNS records
In your provider’s customer area you find the DNS settings. We need two records:
| Type | Name | Value | Meaning |
|---|---|---|---|
| A | @ |
SERVER-IP |
The domain itself (domain.com) points to the server |
| A | * |
SERVER-IP |
All subdomains (blog.domain.com, mail.domain.com etc.) point to the server |
The A record links a name to an IPv4 address. @ stands for the domain itself, and the asterisk * is a wildcard that matches every subdomain. Thanks to the wildcard you never have to create DNS records for new services again. If you run several servers with different IP addresses, create individual records instead of the asterisk. If your server also has an IPv6 address, you can add AAAA records with that address.
This is how it looked for me in the Netcup customer area. The interface may have changed since then; other providers are laid out similarly:

I also reduce the TTL (time to live, how long other servers cache a DNS answer) from 24 hours to about one hour. Then changes take effect faster. Save the settings. It can take a few minutes, in rare cases one or two days, until the records are known everywhere.
Test DNS
You check whether it worked with dig (on Windows with nslookup). You query a subdomain that does not exist yet and still get your server’s IP address back:
dig +short test.{{domain}}203.0.113.10If no answer appears, the records have not been applied yet. Sometimes it helps to flush the DNS cache of your computer (Windows: ipconfig /flushdns).

If your server’s IP address appears, the domain is set up.
Install Traefik 3
We create a folder structure, write the configuration and start Traefik. Everything lives in the folder ~/docker that we created earlier.
Create folders and files
cd ~/docker
mkdir -p traefik/acme traefik/rules traefik/logs shared
touch traefik/acme/acme.json
chmod 600 traefik/acme/acme.jsonThe -p option of mkdir also creates missing intermediate folders. Traefik later stores your certificates and the access to Let’s Encrypt in acme.json. The permission 600 means only the owner may read and write the file. Traefik refuses to start otherwise, because a private key must not be readable by everyone.
Afterwards the structure looks like this (the files follow in a moment):
~/docker
├── .env
├── docker-compose.yml
├── shared
│ └── .htpasswd
└── traefik
├── acme
│ └── acme.json
├── logs
├── rules
│ ├── chains.yml
│ └── middlewares.yml
└── traefik.ymlThe .env file
.env holds values that several Compose files need. Docker Compose reads the file automatically if it sits in the same folder. First we need your user ID. It is shown in the output of id:
iduid=1000({{username}}) gid=1000({{username}}) groups=1000({{username}}),27(sudo),100(users),988(docker)The numbers after uid and gid go into the .env. Open the file with nano ~/docker/.env and enter:
PUID=1000
PGID=1000
TZ=Europe/Berlin
USERDIR=/home/{{username}}
DOCKERDIR=/home/{{username}}/docker
DOMAINNAME={{domain}}PUIDandPGID: user and group ID. Many container images (for example from LinuxServer.io) then run under your user instead of as root.TZ: time zone for the containers.USERDIRandDOCKERDIR: paths we use in the Compose files.pwdshows the path of your current folder.DOMAINNAME: your domain withoutwwwand without a subdomain.
Some people warn against environment variables for secrets. To start with, I still find them better than passwords directly in Compose files that you might store in Git. Important: never put the .env into a public repository.
Prepare password protection (htpasswd)
The Traefik dashboard should not be open to everyone. For that we need a password that Traefik checks as a hash. The program htpasswd from the Apache utilities generates it:
sudo apt install -y apache2-utils
htpasswd -nbB admin 'YourStrongPassword'admin:$2y$05$1eU8Kn67Ix62KNyjfXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXThe options: -n prints the result instead of writing a file, -b takes the password from the command line, and -B uses the secure hash algorithm bcrypt. The output contains username and hash. The password itself is not stored in plain text anywhere. For the real file, use a new password from a password generator and save the output straight into the file:
htpasswd -nbB admin 'YourStrongPassword' > ~/docker/shared/.htpasswdThe static configuration: traefik.yml
This is the main file. It describes Traefik itself and is read at startup. Open nano ~/docker/traefik/traefik.yml:
# Static configuration: Traefik reads it only at startup
global:
checkNewVersion: true
sendAnonymousUsage: false
# Drops headers with similar names such as X_Auth_User so nobody can forge headers
aliasHeadersStrategy: delete
api:
dashboard: true
# Enables the /ping endpoint that Docker's healthcheck queries
ping: {}
log:
level: INFO
accessLog:
filePath: /logs/access.log
bufferingSize: 100
filters:
statusCodes:
- "400-599"
entryPoints:
http:
address: ":80"
http:
redirections:
entryPoint:
to: https
scheme: https
https:
address: ":443"
http:
tls:
certResolver: letsencrypt
providers:
docker:
exposedByDefault: false
network: web
file:
directory: /rules
watch: true
certificatesResolvers:
letsencrypt:
acme:
storage: /acme.json
# For testing: Let's Encrypt staging server (certificates are not trusted, but there are no limits)
caServer: https://acme-staging-v02.api.letsencrypt.org/directory
httpChallenge:
entryPoint: httpWhat is in there, one by one?
global:checkNewVersionoccasionally checks for new Traefik versions,sendAnonymousUsage: falseprevents sending usage statistics.aliasHeadersStrategy: deleteis a protective measure: otherwise attackers can send headers likeX_Auth_User, which some applications read likeX-Auth-User, faking a login. Without the line, Traefik 3.7 warns at startup.api.dashboard: Enables the dashboard. It is not open, but reachable only through the router in the Compose file.ping: A tiny endpoint Docker uses to check whether Traefik is running.logandaccessLog:INFOshows important messages; when there are problems you switch toDEBUG. The access log writes every request into a file. I filter on status codes 400 to 599, that is, errors. That keeps the file small and containing only what interests you.entryPoints: Two entrances. The entrypointhttpon port 80 redirects everything to HTTPS automatically (redirections). So you no longer need your own redirect in every container. The entrypointhttpson port 443 fetches a certificate from the resolverletsencryptfor every domain a router uses. The nameshttpandhttpsare freely chosen; in other guides they are often calledwebandwebsecure. I keephttpandhttpsso my other guides continue to fit.providers: Traefik should read Docker containers.exposedByDefault: falsemeans only containers with the labeltraefik.enable=trueare published.network: webdefines which Docker network Traefik uses to reach the containers. Traefik also reads YAML files from the folder/rulesand notices changes in them immediately (watch: true).certificatesResolvers: The resolverletsencryptfetches certificates via the HTTP challenge. Let’s Encrypt briefly calls your domain on port 80 and checks whether the server belongs to you. That needs no access to your DNS provider and works with any domain. ThecaServerinitially points to the test environment. More on that later.
Prepare middlewares and chains
The dashboard should be password protected. A middleware takes care of that. It lives as a YAML file in the rules folder, which Traefik watches live. Open nano ~/docker/traefik/rules/middlewares.yml:
http:
middlewares:
middlewares-basic-auth:
basicAuth:
realm: "Traefik Basic Auth"
usersFile: /shared/.htpasswd
middlewares-rate-limit:
rateLimit:
average: 100
burst: 50
middlewares-compress:
compress: {}
middlewares-secure-headers:
headers:
stsSeconds: 63072000
stsIncludeSubdomains: true
stsPreload: true
forceSTSHeader: true
customFrameOptionsValue: "SAMEORIGIN"
contentTypeNosniff: true
referrerPolicy: "same-origin"
permissionsPolicy: "camera=(), geolocation=(), microphone=(), payment=(), usb=()"
customResponseHeaders:
X-Robots-Tag: "none,noarchive,nosnippet,notranslate,noimageindex"
server: ""These are four middlewares. Each does one job:
middlewares-basic-auth: Asks for username and password. Traefik reads the credentials from the file.htpasswd.middlewares-rate-limit: Limits how many requests a visitor may send: 100 per second on average, briefly up to 50 more (burst). That slows down simple attacks and bots.middlewares-compress: Compresses responses with gzip (or Brotli and Zstandard, depending on what the browser supports). That saves bandwidth.middlewares-secure-headers: Sets security headers.stsSecondsand the related options tell the browser to open the domain only via HTTPS for two years (HSTS).contentTypeNosniffand the frame option protect against a few typical attacks,referrerPolicylimits how much of the origin address is passed on.permissionsPolicyblocks browser features like camera and microphone in case a page does not need them. The middleware also removes theserverheader and asks search engines viaX-Robots-Tagnot to index the pages. Change that if you want to make a service publicly discoverable.
Entered one by one, that quickly becomes confusing. That is why middlewares are combined into chains. A chain runs several middlewares one after another. Create nano ~/docker/traefik/rules/chains.yml:
http:
middlewares:
chain-no-auth:
chain:
middlewares:
- middlewares-rate-limit
- middlewares-secure-headers
- middlewares-compress
chain-basic-auth:
chain:
middlewares:
- middlewares-rate-limit
- middlewares-secure-headers
- middlewares-compress
- middlewares-basic-authYou now have two chains: chain-no-auth for public services and chain-basic-auth for services with password protection. The router of a service later gets just one entry (for example chain-basic-auth@file) instead of four. The suffix @file tells Traefik the middleware comes from a file (not from Docker labels). The order in the chain matters: the rate limit comes first so attackers do not even reach the password prompt.
The Compose file for Traefik
Now the container is missing. Open nano ~/docker/docker-compose.yml:
networks:
web:
name: web
services:
traefik:
container_name: traefik
image: traefik:v3.7
restart: unless-stopped
security_opt:
- no-new-privileges:true
ports:
- "80:80"
- "443:443"
networks:
- web
environment:
- TZ=$TZ
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
- $DOCKERDIR/traefik/traefik.yml:/etc/traefik/traefik.yml:ro
- $DOCKERDIR/traefik/rules:/rules:ro
- $DOCKERDIR/traefik/acme/acme.json:/acme.json
- $DOCKERDIR/traefik/logs:/logs
- $DOCKERDIR/shared:/shared:ro
healthcheck:
test: ["CMD", "traefik", "healthcheck", "--ping"]
interval: 30s
timeout: 5s
retries: 3
labels:
- "traefik.enable=true"
- "traefik.http.routers.traefik-rtr.entrypoints=https"
- "traefik.http.routers.traefik-rtr.rule=Host(`traefik.$DOMAINNAME`)"
- "traefik.http.routers.traefik-rtr.service=api@internal"
- "traefik.http.routers.traefik-rtr.middlewares=chain-basic-auth@file"This is the central file. Let us go through it:
networks: We create a Docker network calledweb. All services Traefik should publish join this network. Services in other networks are invisible to Traefik. That way you decide what is reachable. You do not necessarily need a manualdocker network create web; Compose does it on the first start.image: traefik:v3.7: I name the version explicitly. Withlatest, an update can silently bring you a new major version that breaks your configuration.v3.7follows all patch updates of the 3.7 series.security_opt: no-new-privileges: Prevents processes in the container from gaining more rights than they had at start.ports: Only 80 and 443 are reachable from outside.volumes: The Docker interface (docker.sock, read-only), the configuration files, the certificate store, the log directory and the folder with the.htpasswd.:romeans “read-only”. We secure the Docker socket further below.healthcheck: Docker calls the ping endpoint every 30 seconds and shows you the statehealthyorunhealthyindocker compose ps.labels: This holds the router for the dashboard. Traefik reads its own labels like those of any other container. The dashboard has an internal service namedapi@internal. The router says: “Requests totraefik.domain.comon the entrypointhttpsgo to the dashboard, protected bychain-basic-auth”.
Docker Compose replaces $TZ, $DOCKERDIR and $DOMAINNAME from the .env. With docker compose config you can display the finished file with the values filled in and find typos:
cd ~/docker
docker compose config --quiet && echo "Configuration OK"Start Traefik
We start with Let’s Encrypt’s staging server. It has no strict limits, but its certificates are not trusted. Real certificates have restrictions (for example at most 50 new certificates per week and domain). If you make a mistake while experimenting, Let’s Encrypt would otherwise lock you out for a while.
cd ~/docker
docker compose up -d
docker compose psNAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
traefik traefik:v3.7 "/entrypoint.sh trae…" traefik 9 seconds ago Up 8 seconds (health: starting) 0.0.0.0:80->80/tcp, [::]:80->80/tcp, 0.0.0.0:443->443/tcp, [::]:443->443/tcpThe healthcheck needs its first run, so about 30 seconds until healthy appears. Meanwhile, look at the log:
docker compose logs traefikWithout errors Traefik starts like this (shortened):
traefik | INF Traefik version 3.7.17 built on 2026-10-30T08:24:21Z version=3.7.17
traefik | INF Starting provider *file.Provider
traefik | INF Starting provider *docker.Provider
traefik | INF Starting provider *acme.ProviderYou may leave the log with Ctrl + C if you started it with -f (docker compose logs -f traefik). You may see a warning about “encoded characters”. It concerns unusual characters in URL paths and is not an error. You can ignore it unless your services explicitly have problems with it.
Open the dashboard
Now open https://traefik.domain.com in the browser. On the first call Traefik fetches the certificate. That takes about 20 to 30 seconds; until then Traefik serves an error page or 404 page not found. That is normal. Wait a moment and reload the page. Because we are in staging mode, the browser shows a certificate warning. That is correct, since no browser trusts the staging certificate. You can click through the warning for the test. After that the page asks for the username and password from the .htpasswd.
In the log you can see how the certificate is created:
traefik | INF Obtaining bundled SAN certificate. domains=traefik.{{domain}}
traefik | INF Validations succeeded; requesting certificates. domains=traefik.{{domain}}
traefik | INF Server responded with a certificate. domains=traefik.{{domain}}You check in the console whether the certificate comes from the staging server:
echo | openssl s_client -connect traefik.{{domain}}:443 -servername traefik.{{domain}} 2>/dev/null | openssl x509 -noout -issuerissuer=C = US, O = Let's Encrypt, CN = (STAGING) Ersatz Emmer YR2If (STAGING) is there, everything worked and we can switch to real certificates. If the dashboard stays empty permanently or the certificate stays TRAEFIK DEFAULT CERT, the section Troubleshooting helps.
Switch to real certificates
For that we comment out the caServer. After that Traefik knows only Let’s Encrypt’s normal server. Certificates from the staging server remain stored in acme.json, though. Traefik would keep using them, so we empty the file:
cd ~/docker
nano traefik/traefik.yml # caServer: https://acme-staging-v02.api.letsencrypt.org/directorydocker compose stop traefik
: > traefik/acme/acme.json
docker compose up -dThe command : > file empties a file without deleting it. The permission 600 is preserved. Open the dashboard again, wait about half a minute again and check the issuer:
echo | openssl s_client -connect traefik.{{domain}}:443 -servername traefik.{{domain}} 2>/dev/null | openssl x509 -noout -issuer -datesissuer=C = US, O = Let's Encrypt, CN = YR2
notBefore=Nov 5 08:03:15 2026 GMT
notAfter=Feb 3 08:03:14 2027 GMTNow your browser trusts the certificate. It is valid for 90 days, and Traefik renews it automatically.
Get to know the dashboard
The dashboard is an important tool for seeing what Traefik is doing right now. The start page shows the entrypoints and a summary of all routers, services and middlewares. Errors and warnings are marked red and orange:

Under HTTP Routers you see every route. The Provider column shows where it comes from: the Docker icon for labels, a file icon for YAML files and a Traefik icon for internal routes. In my list there are also two entries I did not create myself: http-to-https@internal is the automatic redirect from port 80 to 443, and acme-http@internal answers the validation requests from Let’s Encrypt.

Under HTTP Middlewares you find all middlewares and chains from the files. If a middleware you entered is missing there, something is usually wrong with the file (indentation or a typo). Then check the log.

Connect the first service
Now comes the part we did all this for: a service behind Traefik. As a test I use whoami. It is a tiny web server from the Traefik developers that shows you which request arrived at it. It is well suited for testing routing and middlewares.
Every service gets its own Compose file in the folder ~/docker. Open nano ~/docker/docker-compose-whoami.yml:
name: whoami
networks:
web:
external: true
services:
whoami:
container_name: whoami
image: traefik/whoami:v1.12
restart: unless-stopped
networks:
- web
labels:
- "traefik.enable=true"
- "traefik.http.routers.whoami-rtr.entrypoints=https"
- "traefik.http.routers.whoami-rtr.rule=Host(`whoami.$DOMAINNAME`)"
- "traefik.http.routers.whoami-rtr.middlewares=chain-no-auth@file"Start the service:
docker compose -f docker-compose-whoami.yml up -dWith -f you specify the file because it is not called docker-compose.yml. After about half a minute (again because of the certificate) https://whoami.domain.com answers:
curl https://whoami.{{domain}}Hostname: 19a0bcea57b7
IP: 127.0.0.1
IP: ::1
IP: 172.18.0.3
RemoteAddr: 172.18.0.2:38954
GET / HTTP/1.1
Host: whoami.{{domain}}
User-Agent: curl/8.5.0
Accept: */*
Accept-Encoding: gzip
X-Forwarded-For: 203.0.113.10
X-Forwarded-Host: whoami.{{domain}}
X-Forwarded-Port: 443
X-Forwarded-Proto: https
X-Forwarded-Server: 96c86a6352d4
X-Real-Ip: 203.0.113.10Behind X-Forwarded-For is your IP address and behind X-Forwarded-Host the original domain. Traefik adds exactly these headers so the service knows who called it. Let us go through the Compose file:
name: whoami: Gives the project its own name. Without this line, all Compose files in thedockerfolder would have the same name. That confuses Docker and leads to warnings about “orphans” (stray containers). Alternatively you can use subfolders.networks: The networkwebalready exists (Traefik created it), henceexternal: true.image: traefik/whoami:v1.12: A fixed version again.ports: Missing on purpose. The container publishes no port; Traefik reaches it only through the Docker network itself. So it also has no open flank towards the internet.- Label
traefik.enable=true: Without this label Traefik ignores the container, because we setexposedByDefault: false. - Label
...rtr.entrypoints=https: The router listens only on the entrypointhttps. The entrypoint redirects HTTP requests automatically beforehand. - Label
...rtr.rule=Host(...): The rule for when this router is responsible. Here: when the requested domain iswhoami.domain.com. - Label
...rtr.middlewares=chain-no-auth@file: The chain the request runs through.
You did not see a line for the service: if a container has exactly one port, Traefik detects it by itself. If it offers several or a different one should be used, you add the label traefik.http.services.NAME.loadbalancer.server.port=PORT. The service whoami listens on port 80, so nothing was needed.
The structure of a label always follows the same pattern: traefik.http.routers. + name of the router + . + setting. You choose the names freely; they only have to be unique within Traefik. I append -rtr to routers and -svc to services so I immediately see what is what in the dashboard and log.
Host a website
As a second example I publish a simple website with Nginx. First a small HTML file:
mkdir -p ~/docker/appdata/testseite
nano ~/docker/appdata/testseite/index.html<!doctype html>
<html>
<head>
<title>Test page</title>
</head>
<body>
<p>Hello</p>
</body>
</html>And the matching Compose file:
name: testseite
networks:
web:
external: true
services:
testseite:
container_name: testseite
image: nginx:1.31-alpine
restart: unless-stopped
networks:
- web
volumes:
- $DOCKERDIR/appdata/testseite:/usr/share/nginx/html:ro
labels:
- "traefik.enable=true"
- "traefik.http.routers.testseite-rtr.entrypoints=https"
- "traefik.http.routers.testseite-rtr.rule=Host(`testseite.$DOMAINNAME`)"
- "traefik.http.routers.testseite-rtr.service=testseite-svc"
- "traefik.http.services.testseite-svc.loadbalancer.server.port=80"
- "traefik.http.routers.testseite-rtr.middlewares=chain-no-auth@file"cd ~/docker
docker compose -f docker-compose-testseite.yml up -dHere I named the service explicitly and gave the port The page is reachable a few moments later at testseite.domain.com. You create a second, password-protected page the same way. Change folder, names and domain and swap the chain for chain-basic-auth@file:
- "traefik.http.routers.testseite2-rtr.middlewares=chain-basic-auth@file"Traefik detects new containers by itself. You neither have to restart Traefik nor change a file for it. This point distinguishes Traefik from classic reverse proxies, where you enter every new site into a central configuration. All further services from my guides follow the same scheme.
If a service does not show up, check with docker compose -f FILE ps whether the container is running, and in the dashboard whether the router appears.
Middlewares in detail
Middlewares are the most powerful tool in Traefik. We set up four. Now we try them out and get to know a few more. I ran all tests with whoami.
Check security headers
Query the service with curl -I, which shows only the headers of the response:
curl -I https://whoami.{{domain}}HTTP/2 200
content-type: text/plain; charset=utf-8
date: Thu, 05 Nov 2026 11:43:39 GMT
permissions-policy: camera=(), geolocation=(), microphone=(), payment=(), usb=()
referrer-policy: same-origin
strict-transport-security: max-age=63072000; includeSubDomains; preload
x-content-type-options: nosniff
x-frame-options: SAMEORIGIN
x-robots-tag: none,noarchive,nosnippet,notranslate,noimageindex
content-length: 340The headers come from the middleware middlewares-secure-headers. Note that no server header appears either, as we wanted. With services like securityheaders.com you can check the effect from outside.
Check compression
The middleware middlewares-compress compresses responses. You can see it in the transferred size. For that, whoami returns exactly 5000 bytes of text via /data?size=5000:
curl -s -o /dev/null -w "without gzip: %{size_download} bytes\n" "https://whoami.{{domain}}/data?size=5000"
curl -s -o /dev/null -w "with gzip: %{size_download} bytes\n" -H "Accept-Encoding: gzip" "https://whoami.{{domain}}/data?size=5000"without gzip: 5000 bytes
with gzip: 101 bytesTraefik compresses only from a certain size on (1024 bytes by default). With very small responses you therefore see no difference.
Check the rate limit
The rate limit first lets 100 requests per second through and then slows down with the status code 429 Too Many Requests. We send 500 requests at once (curl --parallel bundles them over one HTTP/2 connection):
curl -s --parallel --parallel-max 100 -o /dev/null -w "%{http_code}\n" "https://whoami.{{domain}}/?[1-500]" | sort | uniq -c 57 200
443 429Only about 100 requests plus the burst get through; Traefik rejects the rest. The exact numbers vary with timing.
Change files live
The middlewares live in files that Traefik watches. Changes apply immediately, without a restart. As a test, change burst: 50 to burst: 10:
sed -i "s/burst: 50/burst: 10/" ~/docker/traefik/rules/middlewares.yml
curl -s --parallel --parallel-max 100 -o /dev/null -w "%{http_code}\n" "https://whoami.{{domain}}/?[1-500]" | sort | uniq -c 15 200
485 429Now the limit blocks far more requests, and that without a restart. Afterwards set the value back to 50. Changes to the labels of a container, in contrast, take effect only when you recreate the container with docker compose ... up -d. Changes to traefik.yml need a restart of Traefik.
Restrict access by IP address
With ipAllowList you let only certain addresses through, for example your own or that of your home network. That makes sense for admin interfaces. Add to middlewares.yml:
middlewares-ip-allow:
ipAllowList:
sourceRange:
- "{{server_ip}}/32"The notation /32 stands for exactly one address. With /24 you allow a whole network of 256 addresses. The router who2 with this middleware lets the server itself through, while my computer gets 403 Forbidden:
from the server: 200
from my Mac: 403If Traefik sits behind another proxy (for example Cloudflare), it only sees that proxy’s address. Then you must use ipStrategy to define which header Traefik takes the real address from.
Password protection directly in the labels
You can also attach simple middlewares directly to the container as a label instead of writing them into a file. That is handy for one-off cases. Here is password protection for a single service:
htpasswd -nbB demo 'demopassword' | sed -e 's/\$/$$/g'demo:$$2y$$05$$nHbsDFiydw6270Cte2ym2e353xKr0SyG1mRy0u/d.iaVT...The sed doubles every dollar sign. That is necessary because Docker Compose reads $ as the start of a variable (like $DOMAINNAME). With $$ you write a real dollar sign. The .htpasswd file does not have this problem; the hash stays unchanged there. The labels look like this:
labels:
- "traefik.http.routers.who2-rtr.middlewares=who2-auth"
- "traefik.http.middlewares.who2-auth.basicauth.users=demo:$$2y$$05$$nHbsDFiydw6270Cte2ym2e353xKr0SyG1mRy0u/d.iaVT..."Without a login the service answers with 401 Unauthorized, with the right credentials with 200. You separate several middlewares with a comma, for example chain-no-auth@file,who2-auth. Their order decides what is checked first: if the IP restriction comes before the password protection, foreign addresses immediately get 403, otherwise 401 first.
Forward paths
Routers can react not only to domains but also to paths. You need that when different services should run under the same domain. The middleware stripPrefix removes the path before the request arrives at the service:
labels:
- "traefik.http.routers.who2-api-rtr.entrypoints=https"
- "traefik.http.routers.who2-api-rtr.rule=Host(`who2.$DOMAINNAME`) && PathPrefix(`/api`)"
- "traefik.http.routers.who2-api-rtr.priority=100"
- "traefik.http.routers.who2-api-rtr.middlewares=who2-strip"
- "traefik.http.middlewares.who2-strip.stripprefix.prefixes=/api"A call to https://who2.domain.com/api/hallo arrives at the service as GET /hallo. The priority makes sure this more specific router wins over the general one. Otherwise Traefik sorts routers by the length of their rule.
More useful middlewares
The Traefik documentation lists over 25 middlewares. You need these most often:
| Middleware | What for |
|---|---|
redirectRegex |
Redirect addresses, for example www.domain.com to domain.com |
retry |
Automatically repeat failed requests |
circuitBreaker |
Temporarily switch off a service after many errors |
buffering |
Limit or buffer larger uploads |
addPrefix / replacePath |
Rewrite paths before the service |
errors |
Show custom error pages |
The syntax is always similar. In YAML files you write the name of the middleware and its options; in labels you attach them to traefik.http.middlewares.NAME.. The dashboard shows you whether Traefik understood the configuration.
Wildcard certificate via DNS challenge (optional)
So far Traefik fetches its own certificate for every subdomain. That is enough for most people. A wildcard certificate (*.domain.com), in contrast, is valid for all subdomains at once. It pays off if you run many services and do not want subdomains to show up publicly in the certificate register (Certificate Transparency). For that, Let’s Encrypt requires the DNS challenge: Traefik proves the domain belongs to you by creating a DNS record. For that, Traefik needs access to your DNS provider. This method works only with providers that have an API. The list of supported providers is long (among others Netcup, Cloudflare, Hetzner, IONOS and many more).
At Netcup you need three details: customer number, API key and API password. In the customer area (CCP) you find the menu item “API” under the master data. There you generate key and password. Read the terms of use beforehand. The key can also be used to order domains, so treat the values like a password.

Enter the values in the .env:
NETCUP_CUSTOMER_NUMBER=12345
NETCUP_API_KEY=your-api-key
NETCUP_API_PASSWORD=your-api-passwordThen you add a second resolver in traefik.yml that uses the DNS challenge, and attach it to the entrypoint https:
entryPoints:
https:
address: ":443"
http:
tls:
certResolver: letsencrypt-dns
certResolver: letsencrypt
domains:
- main: "{{domain}}"
sans:
- "*.{{domain}}"
certificatesResolvers:
letsencrypt-dns:
acme:
storage: /acme.json
dnsChallenge:
provider: netcup
resolvers:
- "1.1.1.1:53"
- "8.8.8.8:53"
propagation:
delayBeforeChecks: 60sAnd in Traefik’s Compose file you pass the credentials on to the container:
environment:
- TZ=$TZ
- NETCUP_CUSTOMER_NUMBER=$NETCUP_CUSTOMER_NUMBER
- NETCUP_API_KEY=$NETCUP_API_KEY
- NETCUP_API_PASSWORD=$NETCUP_API_PASSWORDWith domains, Traefik requests a certificate for the main domain and all subdomains on first start. The option delayBeforeChecks gives the DNS provider time to distribute the new record. Because of the wait, issuing takes about 5 minutes. If you wait less, you may wrongly consider it failed. If you use another provider, replace netcup with your provider’s name and the three variables with the details it requires. They are listed in the provider’s documentation. If you change DNS provider or have no API, stay with the HTTP challenge.
Set up Google login (optional)
Password protection with basic auth is simple but inconvenient: you type username and password on every device and cannot block users centrally. Better is a single sign-on with an account you already have, for example Google. The flow is called forward auth: on every request Traefik asks a small service whether the visitor is logged in. If not, the service redirects to Google. After login, a cookie remembers who you are.
For this I use traefik-forward-auth version 4. The project is actively developed, supports Microsoft, GitHub and OpenID Connect providers besides Google, and replaces the older project by Thomas Seddon that I used in the first version.
Create the Google access
You have to register in the Google Cloud Console (free) and create an OAuth client. I describe the steps as the interface was last laid out. Google changes it often, so menu names may differ:
- Create a new project and give it a name you will recognize.
- Open the area Google Auth Platform (formerly: APIs & Services, OAuth consent screen) and set up the consent screen: app name, your email address and “External” as the audience.
- Enter your own Google address under test users. The app stays in test mode, and only these addresses may log in. That is enough for private services.
- Under Clients create a new OAuth client of type “Web application”.
- Enter this address under authorized redirect URIs:
https://oauth.domain.com/portals/main/oauth2/callback
Google then shows you the client ID and client secret. Copy both.
Configure the service
Create a folder and the configuration file. The credentials are in this file, not in the .env. So protect it with chmod 600. The container then runs as your user (user: "$PUID:$PGID" in the Compose file below), otherwise it could not read the file:
mkdir -p ~/docker/oauth
nano ~/docker/oauth/config.yaml
chmod 600 ~/docker/oauth/config.yamlserver:
domains:
- domain: "{{domain}}"
authHost: "oauth.{{domain}}"
portals:
- name: "main"
providers:
- google:
clientID: "YOUR-CLIENT-ID.apps.googleusercontent.com"
clientSecret: "YOUR-CLIENT-SECRET"Under domain is the domain the cookie applies to. That way one login is enough for all your subdomains. authHost is the address of the login service itself. The word main stands for the login portal and appears in the callback address.
Now the container:
name: oauth
networks:
web:
external: true
services:
oauth:
container_name: oauth
image: ghcr.io/italypaleale/traefik-forward-auth:4
restart: unless-stopped
user: "$PUID:$PGID"
networks:
- web
volumes:
- $DOCKERDIR/oauth/config.yaml:/etc/traefik-forward-auth/config.yaml:ro
labels:
- "traefik.enable=true"
- "traefik.http.routers.oauth-rtr.entrypoints=https"
- "traefik.http.routers.oauth-rtr.rule=Host(`oauth.$DOMAINNAME`)"
- "traefik.http.routers.oauth-rtr.service=oauth-svc"
- "traefik.http.services.oauth-svc.loadbalancer.server.port=4181"Middleware and chain
Now comes the middleware that connects Traefik to the login service. Append it to middlewares.yml:
middlewares-oauth-condition:
headers:
customRequestHeaders:
X-Forward-Auth-If: 'Eq("email", "me@{{domain}}")'
middlewares-oauth:
forwardAuth:
address: "http://oauth:4181/portals/main"
trustForwardHeader: true
authResponseHeaders:
- X-Forwarded-User
- X-Forwarded-Displayname
- X-Authenticated-UserWith forwardAuth, Traefik asks the service oauth on every request. If it answers “logged in”, the request continues and the headers from authResponseHeaders (for example the username) are passed to the service. Otherwise the visitor is redirected to Google. The first middleware (middlewares-oauth-condition) restricts access to a specific email address. Replace me@domain.com with your Google address. You join several addresses with ||: Eq("email", "a@gmail.com") || Eq("email", "b@gmail.com"). Without this condition, all Google users the consent page allows could log in.
Finally the chain in chains.yml:
chain-oauth:
chain:
middlewares:
- middlewares-rate-limit
- middlewares-secure-headers
- middlewares-compress
- middlewares-oauth-condition
- middlewares-oauthThe condition has to come before middlewares-oauth, because it sets a header that the login service reads afterwards. Start the service and swap the chain for chain-oauth@file on whoami:
cd ~/docker
docker compose -f docker-compose-oauth.yml up -d
sed -i 's/chain-no-auth@file/chain-oauth@file/' docker-compose-whoami.yml
docker compose -f docker-compose-whoami.yml up -dIf you now open https://whoami.domain.com in the browser, you land at Google. In the terminal you can see the redirects if you follow the path with curl:
curl -skL -c /tmp/jar -b /tmp/jar -o /dev/null -w "%{http_code} %{url_effective}\n" https://whoami.{{domain}}After login you return to whoami automatically. The login service issues cookies that also apply to all other subdomains. So you do not need a second login there.
If the services have their own login and the Google account should merely be an additional hurdle, use chain-oauth for the admin pages. For public websites you stay with chain-no-auth.
Secure the Docker socket (optional)
Traefik needs the Docker socket to detect containers. Whoever controls it controls Docker, and with it practically the server. Even with :ro, an attacker who takes over Traefik can start new containers through the socket. A socket proxy closes this gap. It sits between Traefik and the socket and allows only the read queries Traefik really needs.
For this I use the Docker Socket Proxy by Tecnativa. The changes to Traefik’s docker-compose.yml:
networks:
web:
name: web
socket:
name: socket
internal: true
services:
socket-proxy:
container_name: socket-proxy
image: tecnativa/docker-socket-proxy:v0.5.0
restart: unless-stopped
networks:
- socket
environment:
- CONTAINERS=1
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
traefik:
# ...
networks:
- web
- socket
depends_on:
- socket-proxy
volumes:
- /var/run/docker.sock:/var/run/docker.sock:roAnd in traefik.yml the Docker provider points to the proxy:
providers:
docker:
endpoint: tcp://socket-proxy:2375
exposedByDefault: false
network: webThe network socket has internal: true: it has no access to the internet, and only Traefik and the proxy are in it. With CONTAINERS=1 the proxy allows only reading the container list. It refuses everything else. An attempt to create a container or list images through the proxy ends with 403 Forbidden. After docker compose up -d all services keep running unchanged, but Traefik’s container no longer has a socket:
docker exec traefik ls /var/run/docker.sockls: /var/run/docker.sock: No such file or directoryMoving from Traefik 2 to 3
| Traefik 2 | Traefik 3 | Consequence if you change nothing |
|---|---|---|
HostRegexp(`{host:.+}`) |
HostRegexp(`.+`) (plain regex without a name) |
The rule matches nothing anymore. A HTTP-to-HTTPS redirect built with it does not trigger |
sslRedirect: true in the headers |
Entrypoint redirect (redirections) |
The option is silently ignored, there is no redirect |
featurePolicy: ... |
permissionsPolicy: ... |
The header is missing, you have no protection but do not notice |
browserXssFilter: true |
removed | Sets the obsolete header X-XSS-Protection, which modern browsers ignore |
customFrameOptionsValue: "allow-from ..." |
SAMEORIGIN or frameDeny |
Browsers ignore allow-from |
ipWhiteList |
ipAllowList |
Still works but is deprecated |
TOML files in rules |
YAML or TOML (both work) | None, YAML is just more common |
--api.insecure / port 8080 |
Router with api@internal |
Dashboard without a password on the network |
docker-compose with version: "3.7" |
docker compose, without version |
A warning, because version is obsolete |
thomseddon/traefik-forward-auth:latest |
ghcr.io/italypaleale/traefik-forward-auth:4 |
Keeps working but is hardly maintained anymore |
The trickiest are the settings that do not fail with an error but silently stay without effect. When you update, check routers and headers specifically with curl -I, as shown in this blog post.
Updates and maintenance
Update Traefik: With v3.7 you automatically stay on the patch versions of the 3.7 series. To update, you pull the image again and restart the container:
cd ~/docker
docker compose pull
docker compose up -d
docker image prune -fThe last command deletes old images that are no longer needed. You move to a new major version (for example 3.8 or 4.0) deliberately by changing the tag in the Compose file. Read the Traefik developers’ migration guide first.
Backup: What matters are traefik.yml, the files in the rules folder, .env, .htpasswd and acme.json. The latter contains your certificates. You can have them issued again, but because of the Let’s Encrypt limits it is more convenient to back them up.
Viewing logs: There are three places to look at what Traefik is doing: the container log shows messages and errors. The file ~/docker/traefik/logs/access.log contains the rejected requests (status codes 400 to 599). The dashboard shows the current state. The access log looks like this:
203.0.113.10 - demo [05/Nov/2026:08:53:06 +0000] "GET / HTTP/2.0" 401 17 "-" "-" 629 "who2-rtr@docker" "-" 0ms
198.51.100.7 - - [05/Nov/2026:08:53:36 +0000] "GET / HTTP/2.0" 403 9 "-" "-" 632 "who2-rtr@docker" "-" 0msEach line contains the visitor’s address, the user (if logged in), time, request, status code and the name of the router. That helps when you want to trace who got locked out. The file grows only slowly because it contains only errors. If you need all requests, remove the statusCodes filter in traefik.yml and set up log rotation.
Troubleshooting
When something does not work, proceed in this order: Is the container running (docker compose ps)? What does the log say (docker compose logs traefik)? What does the dashboard show? The most common cases, which I reproduced:
404 page not foundright after the start: Traefik needs up to 40 seconds until the routes are loaded. Wait a moment and try again.404for a service that should be running: Usuallytraefik.enable=trueis missing. Without the label Traefik ignores the container whenexposedByDefaultisfalse. Look in the dashboard to see whether the router appears. A typo in the host in the rule (Host(...)) also leads to404.404for an unknown domain or the IP address: That is intended. Traefik answers only for domains that have a router.504 Gateway Timeout: The container is not in the networkweb. The log then saysCould not find network named "web" for container ...followed byDefaulting to first available network. Addnetworks: [web]to the service.502 Bad Gateway: Traefik reaches the container, but not on the given port. Check the labelloadbalancer.server.portand which port the application really uses in the container (this has nothing to do with the port on the server).- Browser shows a certificate warning: Either you are still in staging mode (issuer
(STAGING)) or Traefik has not issued a certificate yet (TRAEFIK DEFAULT CERT). Wait about 30 seconds and look in the log forObtaining bundled SAN certificate. If it stays empty, check whether the domain points to your IP address (dig +short), whether port 80 is open in the firewall and whether you have just hit the Let’s Encrypt limit. - The router does not appear in the dashboard: For files it is usually indentation or a typo in
rules/*.yml.docker compose logs traefikshows the error message. For labels,docker compose confighelps to see what actually arrives. $characters in labels: Compose reads a single$as a variable. Double it ($$) or use a file.
With the line level: DEBUG in traefik.yml, Traefik shows in great detail what it is doing. That produces a lot of text, so use it only for troubleshooting and set it back to INFO afterwards.
Frequently asked questions
What is the difference between Traefik, Nginx Proxy Manager and Caddy?
All three are reverse proxies. Nginx Proxy Manager has a web interface where you enter every site by hand. Caddy needs only a very short configuration, but you have to write containers into the file yourself. Traefik reads Docker containers and configures itself via labels, which saves work with many changing services. In return Traefik has a steeper learning curve.
Do I need a domain for Traefik?
For HTTPS with a trusted certificate, yes. Let's Encrypt does not issue certificates for bare IP addresses. For tests in your own network you can also use Traefik without a domain and without HTTPS; then certificates and redirect are not needed.
Why use Let's Encrypt's staging server first?
The normal server has limits, for example at most 50 new certificates per week and registered domain. A mistake while experimenting can lock you out for a while. The staging server has no such limits, but no browser trusts its certificates. When everything works there, you switch to the real server.
HTTP challenge or DNS challenge?
The HTTP challenge is simpler: it works with any DNS provider and needs only port 80. It issues one certificate per subdomain, though, and the server must be reachable from the internet. The DNS challenge needs an API from your DNS provider, but can issue wildcard certificates and also works for servers without a public port 80.
How do I connect a new service to Traefik?
Put the container in the network web and set the labels traefik.enable=true, a router with a Host rule and the entrypoint https, plus optionally a middleware chain. If the container has several ports, you give the right one with loadbalancer.server.port. After that docker compose up -d is enough; Traefik does not need to be restarted.
Why do I get a 404 right after the start?
After the start Traefik checks the certificates and reads in the Docker containers. In my tests that takes up to 40 seconds. Until then Traefik answers with 404. A permanent 404 usually has another cause, for example a missing traefik.enable=true or a typo in the Host rule.
Is the Docker socket in Traefik a security risk?
Yes, to a degree. Whoever controls the socket controls Docker. You can reduce the risk with a socket proxy that passes on only read queries. In the section on the Docker socket I show the setup with docker-socket-proxy.
Why should I avoid the latest tag?
With latest, Docker fetches the newest version on every pull, even if it does not fit your configuration. Anyone who ran Traefik 2 with latest suddenly got Traefik 3 and had to change configurations. With a fixed tag like v3.7 you update deliberately.
My old Traefik 2 configuration no longer works. What should I do?
First check whether you ended up on version 3 (dashboard, top left). The most important changes: HostRegexp without {name:...}, sslRedirect is gone, featurePolicy is now called permissionsPolicy.
Can I use Traefik without Docker?
Yes. Traefik is available as a single binary, and the file provider then replaces the Docker labels. For this guide Docker is the simplest variant, though, because Traefik detects containers by itself.
Conclusion
You now have a server that can provide several services under their own subdomains, with automatic HTTPS, a protected dashboard and reusable middlewares. New services come with a few labels, and you never need to touch Traefik. The settings that will help you most: a fixed image tag instead of latest, the staging procedure before switching to real certificates, and chains instead of single middlewares.
Real services are worth tackling next: Portainer as an interface for your containers, n8n for automations, Ghost as a blog or Plausible for statistics. If you would rather practise the concept with a simple example, Astro and Docker shows how a website ends up in a container. If you have questions, feel free to leave me a comment.
Changelog
Updated for Traefik 3 and Ubuntu 24.04. Configuration in traefik.yml and YAML files, certificates via HTTP challenge, dashboard without an open port, current middleware options, Docker socket proxy, new forward-auth service. New sections on terminology, firewall, troubleshooting, migrating from version 2 and an FAQ.