IT

Applicazioni

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.

10 min di lettura, aggiornato il 18 novembre 2026

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 sudo e appartiene al gruppo docker
  • 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:

Terminale
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.com

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

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

Crea poi la rete Docker condivisa tra Traefik e le applicazioni da pubblicare:

Terminale
docker network create proxy

Passo 3: creare la password della dashboard

Installa htpasswd, poi genera l'hash dell'account admin. Il comando chiede la password due volte:

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

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

Terminale
nano /opt/traefik/compose.yaml

Incolla questo contenuto, sostituendo il dominio, l'indirizzo e-mail e TUO_IP:

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

  traefik:
    image: traefik:v3.7.19
    container_name: traefik
    restart: unless-stopped
    depends_on:
      - socket-proxy
    security_opt:
      - no-new-privileges:true
    ports:
      - "80:80"
      - "443:443"
    command:
      - "--entrypoints.web.address=:80"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--entrypoints.web.http.redirections.entrypoint.permanent=true"
      - "--entrypoints.websecure.address=:443"
      - "--entrypoints.websecure.http.tls=true"
      - "--entrypoints.websecure.http.tls.certresolver=le"
      - "--providers.docker=true"
      - "--providers.docker.endpoint=tcp://socket-proxy:2375"
      - "--providers.docker.exposedbydefault=false"
      - "--providers.docker.network=proxy"
      - "--api.dashboard=true"
      - "--api.insecure=false"
      - "--certificatesresolvers.le.acme.email=admin@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:

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

I due servizi devono essere nello stato running. Segui l'avvio nei log, poi esci con Ctrl+C:

Terminale
docker compose logs -f traefik

Passo 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 sezione ports.
  • 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:

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

networks:
  proxy:
    external: true

Avviala:

Terminale
cd /opt/whoami
docker compose up -d

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

Terminale
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 -dates

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

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

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

Terminale
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:8080

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

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

Se 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

YAML
- "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:

YAML
- "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:

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

L'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
Terminale
sudo tar -czf /root/traefik-$(date +%F).tar.gz -C /opt traefik
sudo chmod 600 /root/traefik-$(date +%F).tar.gz

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

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

In caso di problemi

Inizia consultando i log:

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

port is already allocated o address already in use

Un altro servizio occupa la porta 80 o 443:

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

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

Failed to retrieve information of the docker client and server host

Traefik 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 riceve 403 Forbidden quando elenca i container.
  • Se il proxy non ha il diritto di aprire il socket, il suo editore indica che privileged: true può 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:

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

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

L'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:

Terminale
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:unauthorized o connection: 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:

YAML
- "--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:

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

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

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

Riferimenti