Traefik come reverse proxy con Docker
Distribuire Traefik con Docker Compose su Debian o Ubuntu: HTTPS automatico con Let's Encrypt, pubblicazione tramite label, dashboard protetta, aggiornamenti e backup.
In questa pagina
I tuoi valori
Inseriscili una volta: i comandi della guida si aggiornano.
Questa guida spiega come mettere Traefik davanti ai tuoi container Docker. Traefik riceve i visitatori sulle porte 80 e 443, ottiene e rinnova i certificati Let's Encrypt, poi inoltra ogni richiesta al container giusto in base alle sue label.
Al termine della guida, un'applicazione di prova risponde su https://app.tuo-dominio.com. La dashboard di Traefik è disponibile su https://traefik.tuo-dominio.com, solo dal tuo indirizzo IP e con una password. Saprai anche aggiornare ed eseguire il backup dell'installazione.
Le versioni indicate sono le ultime versioni stabili al momento della stesura, a novembre 2026: Traefik v3.7.19 e whoami v1.12.0.
Ordina un Server
Questa guida si applica ai server che amministri tu stesso:
Prerequisiti
- Un server con Debian 12 o 13, oppure Ubuntu 22.04 o 24.04
- Un accesso SSH con un utente che dispone di
sudoe appartiene al gruppodocker - Docker Engine e Docker Compose, installati con la guida Installare Docker Engine e Docker Compose
- Un nome di dominio di cui gestisci la zona DNS
- Nessun altro software sulle porte 80 e 443, come Nginx, Apache, Caddy o Nginx Proxy Manager
- Un indirizzo IP fisso sul tuo computer per accedere alla dashboard, oppure una VPN
Porte utilizzate
| Porta | Direzione | Ruolo | Da aprire |
|---|---|---|---|
| 80/tcp | In entrata | Validazione HTTP-01 e reindirizzamento a HTTPS | Sì |
| 443/tcp | In entrata | Siti in HTTPS e dashboard | Sì |
| 8080/tcp | Nessuna | API non protetta di Traefik, qui disattivata | No |
| 2375/tcp | Rete Docker interna | Proxy del socket Docker, mai pubblicato sul server | No |
Passo 1: far puntare i nomi al server
Crea due record A verso IP_DEL_TUO_SERVER: app.tuo-dominio.com e traefik.tuo-dominio.com. Se il tuo dominio è gestito presso HostMyServers, segui la guida Creare un record A.
Verifica poi il risultato dal server:
sudo apt update
sudo apt install -y bind9-dnsutils
dig +short A app.tuo-dominio.com
dig +short A traefik.tuo-dominio.com
dig +short AAAA traefik.tuo-dominio.comI primi due comandi devono restituire l'indirizzo del tuo server. L'ultimo deve restare vuoto: la dashboard è filtrata per indirizzo IPv4 e una connessione in IPv6 verrebbe rifiutata.
Passo 2: preparare le cartelle e la rete
Crea la cartella del progetto e il file che conterrà i certificati. Traefik rifiuta questo file se altri utenti, oltre al proprietario, possono leggerlo.
sudo install -d -o "$USER" -g "$USER" /opt/traefik /opt/traefik/letsencrypt
cd /opt/traefik
touch letsencrypt/acme.json
chmod 600 letsencrypt/acme.jsonCrea poi la rete Docker condivisa tra Traefik e le applicazioni da pubblicare:
docker network create proxyPasso 3: creare la password della dashboard
Installa htpasswd, poi genera l'hash dell'account admin. Il comando chiede la password due volte:
sudo apt install -y apache2-utils
htpasswd -nB admin > /opt/traefik/dashboard.htpasswd
chmod 600 /opt/traefik/dashboard.htpasswdIl file contiene un hash bcrypt, non la password in chiaro. Inserirlo in un file evita di dover raddoppiare i caratteri $ nelle label di Docker Compose.
Passo 4: scrivere il file Compose
Crea il file:
nano /opt/traefik/compose.yamlIncolla questo contenuto, sostituendo il dominio, l'indirizzo e-mail e TUO_IP:
services:
socket-proxy:
image: tecnativa/docker-socket-proxy:3.4
container_name: traefik-socket-proxy
restart: unless-stopped
environment:
CONTAINERS: "1"
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
networks:
- socket
traefik:
image: traefik:v3.7.19
container_name: traefik
restart: unless-stopped
depends_on:
- socket-proxy
security_opt:
- no-new-privileges:true
ports:
- "80:80"
- "443:443"
command:
- "--entrypoints.web.address=:80"
- "--entrypoints.web.http.redirections.entrypoint.to=websecure"
- "--entrypoints.web.http.redirections.entrypoint.scheme=https"
- "--entrypoints.web.http.redirections.entrypoint.permanent=true"
- "--entrypoints.websecure.address=:443"
- "--entrypoints.websecure.http.tls=true"
- "--entrypoints.websecure.http.tls.certresolver=le"
- "--providers.docker=true"
- "--providers.docker.endpoint=tcp://socket-proxy:2375"
- "--providers.docker.exposedbydefault=false"
- "--providers.docker.network=proxy"
- "--api.dashboard=true"
- "--api.insecure=false"
- "--certificatesresolvers.le.acme.email=admin@tuo-dominio.com"
- "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"
- "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
- "--log.level=INFO"
- "--accesslog=true"
volumes:
- ./letsencrypt:/letsencrypt
- ./dashboard.htpasswd:/etc/traefik/dashboard.htpasswd:ro
networks:
- proxy
- socket
labels:
- "traefik.enable=true"
- "traefik.http.routers.dashboard.rule=Host(`traefik.tuo-dominio.com`)"
- "traefik.http.routers.dashboard.entrypoints=websecure"
- "traefik.http.routers.dashboard.service=api@internal"
- "traefik.http.routers.dashboard.middlewares=dashboard-ip,dashboard-auth"
- "traefik.http.middlewares.dashboard-ip.ipallowlist.sourcerange=TUO_IP/32"
- "traefik.http.middlewares.dashboard-auth.basicauth.usersfile=/etc/traefik/dashboard.htpasswd"
networks:
proxy:
external: true
socket:
internal: true| Elemento | Ruolo |
|---|---|
socket-proxy |
Filtra l'accesso all'API Docker: Traefik può leggere i container, ma non crearli né modificarli |
CONTAINERS: "1" |
Consente la lettura dei container, mentre le richieste di scrittura restano bloccate per impostazione predefinita |
socket |
Rete interna, senza accesso a Internet, riservata a Traefik e al proxy |
exposedbydefault=false |
Vengono pubblicati solo i container che riportano traefik.enable=true |
network=proxy |
Traefik raggiunge le applicazioni attraverso questa rete |
httpchallenge |
Let's Encrypt convalida ogni nome sulla porta 80 |
certresolver=le |
Tutti i siti del punto di ingresso HTTPS ricevono un certificato |
api@internal |
Servizio interno che fornisce la dashboard |
dashboard-ip poi dashboard-auth |
Filtra l'indirizzo IP, poi richiede la password |
Traefik non monta direttamente il socket Docker: se il container esposto a Internet venisse compromesso, l'attaccante non otterrebbe il controllo di Docker. È una delle protezioni raccomandate dalla documentazione di Traefik.
Passo 5: avviare Traefik
Convalida il file, poi avvia i container:
cd /opt/traefik
docker compose config --quiet
docker compose up -d
docker compose psI due servizi devono essere nello stato running. Segui l'avvio nei log, poi esci con Ctrl+C:
docker compose logs -f traefikPasso 6: controllare il firewall
Docker pubblica le porte 80 e 443 con le proprie regole, applicate prima di quelle di UFW. Queste due porte sono quindi raggiungibili anche senza ufw allow, e UFW non può limitarle. La guida Configurare il firewall UFW descrive in dettaglio questo funzionamento.
Ne derivano due regole:
- Non pubblicare le porte delle tue applicazioni: restano sulla rete
proxy, senza sezioneports. - Se usi il firewall integrato della tua istanza, autorizza anche le porte 80 e 443 dalla tua area clienti.
Passo 7: pubblicare un'applicazione
Crea un'applicazione di prova nella sua cartella:
sudo install -d -o "$USER" -g "$USER" /opt/whoami
nano /opt/whoami/compose.yamlservices:
whoami:
image: traefik/whoami:v1.12.0
restart: unless-stopped
networks:
- proxy
labels:
- "traefik.enable=true"
- "traefik.http.routers.whoami.rule=Host(`app.tuo-dominio.com`)"
- "traefik.http.routers.whoami.entrypoints=websecure"
- "traefik.http.services.whoami.loadbalancer.server.port=80"
networks:
proxy:
external: trueAvviala:
cd /opt/whoami
docker compose up -dTraefik rileva da solo il container, senza riavvio. La label loadbalancer.server.port indica la porta di ascolto all'interno del container. Per le tue applicazioni, riprendi queste quattro label cambiando il nome del router, il dominio e la porta.
Verificare il risultato
Testa entrambi i protocolli, poi controlla il certificato:
curl -I http://app.tuo-dominio.com
curl -I https://app.tuo-dominio.com
echo | openssl s_client -connect app.tuo-dominio.com:443 -servername app.tuo-dominio.com 2>/dev/null | openssl x509 -noout -issuer -datesLa richiesta HTTP deve restituire un reindirizzamento 308 verso HTTPS, e la richiesta HTTPS un codice 200. L'emittente del certificato deve essere Let's Encrypt. Il primo certificato può richiedere qualche istante.
Controlla poi che il proxy del socket blocchi davvero ciò che non è autorizzato:
cd /opt/traefik
docker compose exec traefik wget -S -O- http://socket-proxy:2375/images/jsonLa risposta attesa è 403 Forbidden.
Dal tuo computer, testa la dashboard. La prima chiamata deve restituire 401, la seconda la versione di Traefik, e la terza non deve rispondere:
curl -I https://traefik.tuo-dominio.com/dashboard/
curl -u admin https://traefik.tuo-dominio.com/api/version
curl -m 5 http://IP_DEL_TUO_SERVER:8080Apri infine https://traefik.tuo-dominio.com/dashboard/ nel browser. La barra finale è necessaria. Da un altro indirizzo IP, la stessa pagina deve restituire 403.
Gestire l'accesso alla dashboard
Per cambiare la password, rigenera il file e riavvia Traefik:
cd /opt/traefik
htpasswd -nB admin > dashboard.htpasswd
docker compose restart traefikSe il tuo indirizzo IP cambia, modifica la label dashboard-ip in compose.yaml, poi esegui docker compose up -d. Se cambia spesso, riserva piuttosto la dashboard a una rete privata, con WireGuard o Tailscale.
Impostazioni comuni
Rispondere su più nomi
- "traefik.http.routers.whoami.rule=Host(`app.tuo-dominio.com`) || Host(`www.tuo-dominio.com`)"Ogni nome deve puntare al server affinché il certificato venga emesso.
Proteggere un'applicazione con le stesse regole
I middleware dichiarati sul container Traefik sono riutilizzabili dagli altri container, con il suffisso @docker:
- "traefik.http.routers.whoami.middlewares=dashboard-ip@docker,dashboard-auth@docker"Aggiornare
Consulta prima le note di rilascio e, per un cambio di versione minore o maggiore, la guida alla migrazione. Esegui poi il backup dell'installazione, modifica il tag traefik:v3.7.19 in compose.yaml, quindi esegui:
cd /opt/traefik
docker compose pull
docker compose up -d
docker compose exec traefik traefik version
docker compose logs --tail 50 traefikL'immagine tecnativa/docker-socket-proxy:3.4 resta sul ramo HAProxy 3.4 e il suo editore la ricostruisce ogni settimana: docker compose pull scarica questi aggiornamenti. Procedi allo stesso modo in /opt/whoami e nelle cartelle delle tue applicazioni.
Backup e ripristino
La cartella /opt/traefik contiene tutto ciò che occorre conservare:
| Percorso | Contenuto |
|---|---|
compose.yaml |
Configurazione di Traefik e del proxy del socket |
dashboard.htpasswd |
Hash della password della dashboard |
letsencrypt/acme.json |
Certificati, chiavi private e account ACME |
sudo tar -czf /root/traefik-$(date +%F).tar.gz -C /opt traefik
sudo chmod 600 /root/traefik-$(date +%F).tar.gzQuesto archivio contiene chiavi private: copialo fuori dal server in una posizione cifrata. Esegui anche il backup dei file Compose e dei dati delle tue applicazioni.
Per ripristinare l'archivio, sostituendo AAAA-MM-GG con la sua data, crea la rete se non esiste ancora su questo server:
cd /opt/traefik 2>/dev/null && docker compose down
sudo tar -xzf /root/traefik-AAAA-MM-GG.tar.gz -C /opt
docker network create proxy
cd /opt/traefik
docker compose up -dIn caso di problemi
Inizia consultando i log:
cd /opt/traefik
docker compose logs --tail 100 traefik
docker compose logs --tail 50 socket-proxyport is already allocated o address already in use
Un altro servizio occupa la porta 80 o 443:
sudo ss -ltnp | grep -E ':(80|443) '
docker ps --format '{{.Names}} {{.Ports}}'Arresta questo servizio se non ti serve più, ad esempio con sudo systemctl disable --now nginx.
permissions 644 for /letsencrypt/acme.json are too open, please use 600
Correggi i permessi, poi riavvia Traefik:
chmod 600 /opt/traefik/letsencrypt/acme.json
cd /opt/traefik
docker compose restart traefikFailed to retrieve information of the docker client and server host
Traefik non riesce a raggiungere il proxy del socket. Verifica che socket-proxy sia in funzione e che i due servizi condividano la rete socket. A seconda della causa indicata nei suoi log:
- Se il server non ha IPv6 e il proxy non si avvia, aggiungi
DISABLE_IPV6: "1"alle sue variabili d'ambiente. - Se
CONTAINERSè assente, Traefik riceve403 Forbiddenquando elenca i container. - Se il proxy non ha il diritto di aprire il socket, il suo editore indica che
privileged: truepuò essere necessario con alcuni profili SELinux o AppArmor. Aggiungi questa opzione solo come ultima risorsa.
404 page not found
Nessun router corrisponde alla richiesta. Verifica che il container sia avviato, che riporti traefik.enable=true, che il nome in Host() sia esatto e che sia collegato alla rete proxy:
docker network inspect proxy --format '{{range .Containers}}{{.Name}} {{end}}'Bad Gateway o Gateway Timeout
Traefik trova il router ma non raggiunge l'applicazione. Controlla la porta indicata in loadbalancer.server.port, poi esegui un test da Traefik:
cd /opt/traefik
docker compose exec traefik wget -qO- http://whoami:80L'applicazione deve ascoltare su 0.0.0.0 nel suo container. Se ascolta solo su 127.0.0.1, Traefik non può raggiungerla.
Il browser mostra TRAEFIK DEFAULT CERT
Traefik non ha ancora un certificato valido per questo nome e presenta il proprio certificato predefinito. Cerca la causa nei log:
cd /opt/traefik
docker compose logs traefik | grep -iE 'acme|certificate'Unable to obtain ACME certificate for domains
Il messaggio contiene il motivo del rifiuto:
urn:ietf:params:acme:error:dns: il nome non esiste ancora nel DNS oppure non si è propagato.urn:ietf:params:acme:error:unauthorizedoconnection: Let's Encrypt non raggiunge la porta 80. Controlla i record A e AAAA, poi il firewall della tua istanza. Se è tutto corretto, contatta il supporto dalla tua area clienti.urn:ietf:params:acme:error:caa: un record CAA vieta Let's Encrypt.urn:ietf:params:acme:error:rateLimited: sono state inviate troppe richieste. Attendi la fine del periodo indicato.
Per le tue prove, aggiungi temporaneamente l'ambiente di test di Let's Encrypt, i cui certificati non sono riconosciuti dai browser:
- "--certificatesresolvers.le.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory"Prima di tornare in produzione, rimuovi questa riga e svuota acme.json con truncate -s 0 /opt/traefik/letsencrypt/acme.json, senza modificarne i permessi. Esegui poi docker compose up -d.
403 Forbidden sulla dashboard
Il tuo indirizzo IP non è quello della label dashboard-ip. Il log degli accessi indica l'indirizzo visto da Traefik, all'inizio della riga:
cd /opt/traefik
docker compose logs --no-log-prefix traefik | grep 'dashboard@docker' | tail -n 5Se questo indirizzo è quello di un gateway Docker, la connessione è probabilmente arrivata in IPv6: elimina il record AAAA del nome.
is a directory per dashboard.htpasswd
Il file non esisteva al primo avvio e Docker ha creato una cartella al suo posto. Eliminala, ricrea il file, poi riavvia il container:
cd /opt/traefik
docker compose down
sudo rmdir dashboard.htpasswd
htpasswd -nB admin > dashboard.htpasswd
chmod 600 dashboard.htpasswd
docker compose up -d