Deployn

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.

Set Up Traefik 3: Reverse Proxy with Docker, HTTPS and Authentication hero image
Contents
Tested with
Traefik 3.7traefik-forward-auth 4.14Docker 29.9Docker Compose 5.7Ubuntu 24.04
Last checked on

You 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 ► Container

Traefik 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 rules folder.

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.

Terminalbash
ssh root@{{server_ip}}

Windows Terminal

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):

Login

Update the system

First we fetch all updates. apt update downloads the current package list, apt upgrade installs the new versions:

Terminalbash
apt update
apt upgrade -y

The -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:

Terminalbash
hostnamectl set-hostname meinserver
timedatectl set-timezone Europe/Berlin

Check the result with these commands:

Terminalbash
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).

Terminalbash
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:

Terminalbash
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:

Terminalbash
rsync --archive --chown={{username}}:{{username}} ~/.ssh /home/{{username}}

Now log out and log in again with the new user:

Terminalbash
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:

Terminalbash
apt update
Reading 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:

Terminalbash
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status

ufw 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:

Terminalbash
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-plugin

Docker 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:

Terminalbash
sudo usermod -aG docker {{username}}

The group change only applies after a new login. Log out, log in again and test the installation:

Terminalbash
docker --version
docker compose version
docker run --rm hello-world
Docker 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.

Terminalbash
cd ~
mkdir docker
ls

With 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:

Terminalbash
echo "hello" > test.txt
echo "goodbye" >> test.txt
cat test.txt
hello
goodbye

cat 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:

DNS records at Netcup

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:

Terminalbash
dig +short test.{{domain}}
203.0.113.10

If no answer appears, the records have not been applied yet. Sometimes it helps to flush the DNS cache of your computer (Windows: ipconfig /flushdns).

Flush the DNS cache

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

Terminalbash
cd ~/docker
mkdir -p traefik/acme traefik/rules traefik/logs shared
touch traefik/acme/acme.json
chmod 600 traefik/acme/acme.json

The -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.yml

The .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:

Terminalbash
id
uid=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:

.env
PUID=1000
PGID=1000
TZ=Europe/Berlin
USERDIR=/home/{{username}}
DOCKERDIR=/home/{{username}}/docker
DOMAINNAME={{domain}}
  • PUID and PGID: 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.
  • USERDIR and DOCKERDIR: paths we use in the Compose files. pwd shows the path of your current folder.
  • DOMAINNAME: your domain without www and 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:

Terminalbash
sudo apt install -y apache2-utils
htpasswd -nbB admin 'YourStrongPassword'
admin:$2y$05$1eU8Kn67Ix62KNyjfXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

The 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:

Terminalbash
htpasswd -nbB admin 'YourStrongPassword' > ~/docker/shared/.htpasswd

The static configuration: traefik.yml

This is the main file. It describes Traefik itself and is read at startup. Open nano ~/docker/traefik/traefik.yml:

traefik/traefik.ymlyaml
# 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: http

What is in there, one by one?

  • global: checkNewVersion occasionally checks for new Traefik versions, sendAnonymousUsage: false prevents sending usage statistics. aliasHeadersStrategy: delete is a protective measure: otherwise attackers can send headers like X_Auth_User, which some applications read like X-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.
  • log and accessLog: INFO shows important messages; when there are problems you switch to DEBUG. 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 entrypoint http on port 80 redirects everything to HTTPS automatically (redirections). So you no longer need your own redirect in every container. The entrypoint https on port 443 fetches a certificate from the resolver letsencrypt for every domain a router uses. The names http and https are freely chosen; in other guides they are often called web and websecure. I keep http and https so my other guides continue to fit.
  • providers: Traefik should read Docker containers. exposedByDefault: false means only containers with the label traefik.enable=true are published. network: web defines which Docker network Traefik uses to reach the containers. Traefik also reads YAML files from the folder /rules and notices changes in them immediately (watch: true).
  • certificatesResolvers: The resolver letsencrypt fetches 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. The caServer initially 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:

traefik/rules/middlewares.ymlyaml
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. stsSeconds and the related options tell the browser to open the domain only via HTTPS for two years (HSTS). contentTypeNosniff and the frame option protect against a few typical attacks, referrerPolicy limits how much of the origin address is passed on. permissionsPolicy blocks browser features like camera and microphone in case a page does not need them. The middleware also removes the server header and asks search engines via X-Robots-Tag not 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:

traefik/rules/chains.ymlyaml
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-auth

You 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:

docker-compose.ymlyaml
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 called web. 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 manual docker network create web; Compose does it on the first start.
  • image: traefik:v3.7: I name the version explicitly. With latest, an update can silently bring you a new major version that breaks your configuration. v3.7 follows 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. :ro means “read-only”. We secure the Docker socket further below.
  • healthcheck: Docker calls the ping endpoint every 30 seconds and shows you the state healthy or unhealthy in docker 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 named api@internal. The router says: “Requests to traefik.domain.com on the entrypoint https go to the dashboard, protected by chain-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:

Terminalbash
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.

Terminalbash
cd ~/docker
docker compose up -d
docker compose ps
NAME      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/tcp

The healthcheck needs its first run, so about 30 seconds until healthy appears. Meanwhile, look at the log:

Terminalbash
docker compose logs traefik

Without 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.Provider

You 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:

Terminalbash
echo | openssl s_client -connect traefik.{{domain}}:443 -servername traefik.{{domain}} 2>/dev/null | openssl x509 -noout -issuer
issuer=C = US, O = Let's Encrypt, CN = (STAGING) Ersatz Emmer YR2

If (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:

Terminalbash
cd ~/docker
nano traefik/traefik.yml
traefik/traefik.ymlyaml
      # caServer: https://acme-staging-v02.api.letsencrypt.org/directory
Terminalbash
docker compose stop traefik
: > traefik/acme/acme.json
docker compose up -d

The 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:

Terminalbash
echo | openssl s_client -connect traefik.{{domain}}:443 -servername traefik.{{domain}} 2>/dev/null | openssl x509 -noout -issuer -dates
issuer=C = US, O = Let's Encrypt, CN = YR2
notBefore=Nov  5 08:03:15 2026 GMT
notAfter=Feb  3 08:03:14 2027 GMT

Now 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:

The Traefik dashboard with entrypoints and overview

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.

List of HTTP routers in the dashboard

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.

List of middlewares in the dashboard

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:

docker-compose-whoami.ymlyaml
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:

Terminalbash
docker compose -f docker-compose-whoami.yml up -d

With -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:

Terminalbash
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.10

Behind 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 the docker folder would have the same name. That confuses Docker and leads to warnings about “orphans” (stray containers). Alternatively you can use subfolders.
  • networks: The network web already exists (Traefik created it), hence external: 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 set exposedByDefault: false.
  • Label ...rtr.entrypoints=https: The router listens only on the entrypoint https. The entrypoint redirects HTTP requests automatically beforehand.
  • Label ...rtr.rule=Host(...): The rule for when this router is responsible. Here: when the requested domain is whoami.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:

Terminalbash
mkdir -p ~/docker/appdata/testseite
nano ~/docker/appdata/testseite/index.html
index.htmlhtml
<!doctype html>
<html>
	<head>
		<title>Test page</title>
	</head>
	<body>
		<p>Hello</p>
	</body>
</html>

And the matching Compose file:

docker-compose-testseite.ymlyaml
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"
Terminalbash
cd ~/docker
docker compose -f docker-compose-testseite.yml up -d

Here 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:

docker-compose-testseite2.ymlyaml
      - "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:

Terminalbash
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: 340

The 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:

Terminalbash
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 bytes

Traefik 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):

Terminalbash
curl -s --parallel --parallel-max 100 -o /dev/null -w "%{http_code}\n" "https://whoami.{{domain}}/?[1-500]" | sort | uniq -c
     57 200
    443 429

Only 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:

Terminalbash
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 429

Now 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:

traefik/rules/middlewares.ymlyaml
    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:      403

If 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:

Terminalbash
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:

yaml
    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:

yaml
    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.

API activation in the Netcup customer area

Enter the values in the .env:

.env
NETCUP_CUSTOMER_NUMBER=12345
NETCUP_API_KEY=your-api-key
NETCUP_API_PASSWORD=your-api-password

Then you add a second resolver in traefik.yml that uses the DNS challenge, and attach it to the entrypoint https:

traefik/traefik.ymlyaml
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: 60s

And in Traefik’s Compose file you pass the credentials on to the container:

docker-compose.ymlyaml
    environment:
      - TZ=$TZ
      - NETCUP_CUSTOMER_NUMBER=$NETCUP_CUSTOMER_NUMBER
      - NETCUP_API_KEY=$NETCUP_API_KEY
      - NETCUP_API_PASSWORD=$NETCUP_API_PASSWORD

With 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:

  1. Create a new project and give it a name you will recognize.
  2. 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.
  3. 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.
  4. Under Clients create a new OAuth client of type “Web application”.
  5. 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:

Terminalbash
mkdir -p ~/docker/oauth
nano ~/docker/oauth/config.yaml
chmod 600 ~/docker/oauth/config.yaml
oauth/config.yamlyaml
server:
  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:

docker-compose-oauth.ymlyaml
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:

traefik/rules/middlewares.ymlyaml
    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-User

With 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:

traefik/rules/chains.ymlyaml
    chain-oauth:
      chain:
        middlewares:
          - middlewares-rate-limit
          - middlewares-secure-headers
          - middlewares-compress
          - middlewares-oauth-condition
          - middlewares-oauth

The 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:

Terminalbash
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 -d

If 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:

Terminalbash
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:

docker-compose.ymlyaml
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:ro

And in traefik.yml the Docker provider points to the proxy:

traefik/traefik.ymlyaml
providers:
  docker:
    endpoint: tcp://socket-proxy:2375
    exposedByDefault: false
    network: web

The 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:

Terminalbash
docker exec traefik ls /var/run/docker.sock
ls: /var/run/docker.sock: No such file or directory

Moving 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:

Terminalbash
cd ~/docker
docker compose pull
docker compose up -d
docker image prune -f

The 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" "-" 0ms

Each 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 found right after the start: Traefik needs up to 40 seconds until the routes are loaded. Wait a moment and try again.
  • 404 for a service that should be running: Usually traefik.enable=true is missing. Without the label Traefik ignores the container when exposedByDefault is false. Look in the dashboard to see whether the router appears. A typo in the host in the rule (Host(...)) also leads to 404.
  • 404 for 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 network web. The log then says Could not find network named "web" for container ... followed by Defaulting to first available network. Add networks: [web] to the service.
  • 502 Bad Gateway: Traefik reaches the container, but not on the given port. Check the label loadbalancer.server.port and 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 for Obtaining 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 traefik shows the error message. For labels, docker compose config helps 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.

Share
XRedditEmail
Back to all posts

Changelog

  1. 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.

Related articles

Comments