Entenda o Traefik não iniciando: o que verificar e como resolver

16 min de leitura  ·  Guia técnico

Traefik não iniciando é um problema comum em ambientes Docker que ocorre por conflito de porta, erro de sintaxe no arquivo de configuração ou permissão negada ao socket do Docker. Verifique os logs do container com docker logs traefik para identificar a causa exata antes de qualquer alteração. Veja abaixo como diagnosticar e corrigir cada cenário.

Pré-requisitos para diagnosticar o Traefik não iniciando

• Acesso SSH ao servidor com usuário root ou com permissão sudo
• Docker Engine instalado (versão 24 ou superior recomendada) e Docker Compose v2
• Arquivo docker-compose.yml e traefik.yml (ou configuração inline) acessíveis
• Portas 80, 443 e 8080 identificadas — saber quais processos as ocupam
• Permissão de leitura/escrita no arquivo acme.json se TLS automático estiver habilitado
• Distribuição: exemplos testados no Debian 12 e Ubuntu 24.04 LTS

Entenda o Traefik não iniciando: primeiros passos de diagnóstico

Quando o Traefik não inicia, o primeiro recurso é sempre o log do container. Diferente de serviços systemd, o Traefik rodando em Docker registra tudo no stdout, e o comando abaixo exibe as últimas 80 linhas com timestamp:

docker logs traefik --tail 80 --timestamps

2024-11-10T14:22:01Z ERR  error="listen tcp :443: bind: address already in use"
2024-11-10T14:22:01Z ERR  error="listen tcp :80: bind: address already in use"

Se o container sequer aparece em docker ps, ele pode ter saído imediatamente. Confirme o status com:

docker ps -a | grep traefik

a3f1c2d4e5b6   traefik:v3.1   "/entrypoint.sh trae…"   2 minutes ago   Exited (1) 2 minutes ago   traefik

O código de saída Exited (1) indica falha na inicialização. Código Exited (0) indica encerramento limpo — nesse caso, o problema é de configuração que faz o processo terminar sem erro fatal, o que é mais raro mas possível com entrypoints mal definidos.

Verifique também se o arquivo de configuração estático está sendo montado corretamente:

docker inspect traefik | grep -A 20 "Mounts"

Confirme que o caminho do host (Source) existe e que o arquivo dentro do container (Destination) corresponde ao que está declarado no command ou em --configFile.

Para um diagnóstico completo de serviços que falham ao iniciar no Linux, consulte também o artigo Como solucionar problemas de inicialização de serviços no VPS Linux.

Verificar conflito de porta impedindo o Traefik de subir

O conflito de porta é a causa mais frequente de falha de inicialização do Traefik em produção. O proxy reverso precisa das portas 80 e 443 livres no host para receber tráfego externo. Se Apache, Nginx ou outro processo já as ocupa, o bind falha imediatamente.

Identifique qual processo está usando a porta 80:

ss -tlnp | grep ':80'

LISTEN 0 128 0.0.0.0:80 0.0.0.0:* users:(("apache2",pid=1234,fd=4))

Para a porta 443:

ss -tlnp | grep ':443'

Se Apache ou Nginx estiver rodando diretamente no host (fora do Docker), pare o serviço antes de iniciar o Traefik:

systemctl stop apache2
systemctl disable apache2

Ou, se for Nginx:

systemctl stop nginx
systemctl disable nginx

Depois reinicie o container:

docker compose up -d traefik

Se você precisa manter o Nginx no host por outro motivo, a alternativa é configurar o Traefik para escutar em portas alternativas no host e usar o Nginx como proxy para o Traefik — mas isso aumenta a complexidade e raramente é necessário em ambientes de VPS dedicados ao Docker.

Outra situação comum: um container anterior do Traefik ainda está rodando e segurando a porta. Verifique:

docker ps | grep traefik

Se houver um container antigo, remova-o antes de recriar:

docker rm -f traefik

Corrigir erros de sintaxe no traefik.yml e docker-compose.yml

Erros de configuração estática são a segunda causa mais comum de falha. O Traefik valida o arquivo traefik.yml na inicialização e aborta se encontrar chaves inválidas, indentação incorreta ou valores fora do tipo esperado.

Um exemplo de traefik.yml mínimo e funcional para ambiente com Docker e TLS automático:

api:
  dashboard: true
  insecure: true

entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"

providers:
  docker:
    exposedByDefault: false
    network: traefik_net

certificatesResolvers:
  letsencrypt:
    acme:
      email: [email protected]
      storage: /etc/traefik/acme.json
      httpChallenge:
        entryPoint: web

Valide a sintaxe YAML antes de subir o container. Instale o yq ou use Python:

python3 -c "import yaml, sys; yaml.safe_load(open('traefik.yml'))" && echo "YAML válido"

YAML válido

Se o Python retornar um erro como mapping values are not allowed here, a linha indicada tem problema de indentação. YAML é sensível a espaços — nunca use tabs.

No docker-compose.yml, verifique se os volumes estão mapeados corretamente e se a rede está declarada:

version: "3.8"

services:
  traefik:
    image: traefik:v3.1
    container_name: traefik
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./traefik.yml:/etc/traefik/traefik.yml:ro
      - ./acme.json:/etc/traefik/acme.json
    networks:
      - traefik_net

networks:
  traefik_net:
    external: true

Atenção: se a rede traefik_net estiver declarada como external: true, ela precisa existir antes de subir o compose. Crie-a com:

docker network create traefik_net

Resolver problema de permissão no acme.json e socket do Docker

Dois problemas de permissão são recorrentes no Traefik: o arquivo acme.json com permissão incorreta e o socket do Docker inacessível ao container.

O Traefik exige que o acme.json tenha permissão 600 (leitura e escrita apenas pelo dono). Se o arquivo tiver permissão 644 ou 666, o Traefik recusa iniciar com a mensagem:

ERR  error="unsafe permissions on credentials file /etc/traefik/acme.json, expected 0600"

Corrija com:

chmod 600 /caminho/para/acme.json

Se o arquivo não existir, crie-o antes de subir o container:

touch /etc/traefik/acme.json
chmod 600 /etc/traefik/acme.json

Para o socket do Docker, o volume /var/run/docker.sock:/var/run/docker.sock precisa ser acessível. Verifique as permissões do socket no host:

ls -la /var/run/docker.sock

srw-rw---- 1 root docker 0 Nov 10 14:00 /var/run/docker.sock

O grupo docker precisa ter acesso. Se o Traefik rodar como usuário não-root dentro do container, adicione o usuário ao grupo docker no host ou monte o socket com a flag :ro e garanta que o processo interno tenha permissão. Em produção, montar o socket como somente leitura (:ro) é uma boa prática de segurança.

Se você usa SELinux (comum no Rocky Linux 9 ou AlmaLinux 9), o contexto do socket pode bloquear o acesso. Verifique com:

ls -Z /var/run/docker.sock

E ajuste o contexto se necessário:

chcon -t container_file_t /var/run/docker.sock

Diagnosticar roteamento incorreto e labels do Docker

Quando o Traefik inicia mas não roteia para o container correto, o problema geralmente está nas labels do serviço ou na configuração de rede. O dashboard do Traefik em http://IP:8080/dashboard/ é a ferramenta mais rápida para diagnosticar esse cenário — ele exibe rotas ativas, middlewares e erros de configuração em tempo real.

Um exemplo de labels corretas para um container de aplicação web:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.meuapp.rule=Host(`meuapp.exemplo.com`)"
  - "traefik.http.routers.meuapp.entrypoints=websecure"
  - "traefik.http.routers.meuapp.tls.certresolver=letsencrypt"
  - "traefik.http.services.meuapp.loadbalancer.server.port=3000"

Pontos críticos a verificar:

• Rede compartilhada: o container da aplicação deve estar na mesma rede Docker que o Traefik. Adicione a rede no serviço da aplicação no compose.
• traefik.enable=true: obrigatório quando exposedByDefault: false está no traefik.yml.
• Porta do serviço: se o container expõe múltiplas portas, especifique qual o Traefik deve usar com loadbalancer.server.port.
• Backticks no Host: a regra Host() usa backticks, não aspas simples ou duplas.

Para inspecionar a rede e confirmar que os containers estão conectados:

docker network inspect traefik_net

Procure pelo nome do container da aplicação na seção Containers do output. Se ele não aparecer, adicione a rede ao serviço no compose e recrie o container.

Para ambientes com múltiplos serviços Docker, veja também o artigo Como Instalar e Configurar o Docker no VPS Linux para Hospedar Aplicações para garantir que a infraestrutura base está correta.

Problemas comuns e como resolver

Sintoma: Traefik exibe "certificate file not found" e não inicia

Causa: O caminho do certificado TLS manual declarado no traefik.yml não existe dentro do container, ou o volume não foi mapeado corretamente no compose.
Solução: Verifique se o volume que contém os certificados está declarado no docker-compose.yml e se o caminho interno corresponde ao que está no traefik.yml. Execute docker exec traefik ls /etc/traefik/certs/ para confirmar que os arquivos estão acessíveis dentro do container. Se usar Let's Encrypt automático, remova a seção tls.certificates manual e use apenas o certificatesResolvers.

Sintoma: dashboard do Traefik acessível mas nenhuma rota aparece

Causa: O provider Docker está configurado, mas nenhum container tem traefik.enable=true nas labels, ou os containers não estão na rede correta.
Solução: Confirme que exposedByDefault: false está no traefik.yml e que todos os containers que devem ser roteados têm a label traefik.enable=true. Verifique a rede com docker network inspect traefik_net e certifique-se de que os containers da aplicação estão listados. Recrie os containers após adicionar as labels com docker compose up -d --force-recreate nome_servico.

Sintoma: Traefik reinicia em loop com "context deadline exceeded"

Causa: O desafio ACME HTTP-01 está falhando porque a porta 80 não está acessível externamente, ou o DNS do domínio não aponta para o IP do servidor.
Solução: Confirme que o domínio resolve para o IP correto com dig +short meudominio.com. Verifique se o firewall do servidor permite tráfego na porta 80 — o Let's Encrypt precisa alcançar o servidor nessa porta para validar o domínio. No Debian/Ubuntu, libere com ufw allow 80/tcp. Se o servidor estiver atrás de um NAT, configure o port forwarding corretamente.

Sintoma: erro "no such file or directory" ao montar traefik.yml

Causa: O arquivo traefik.yml não existe no caminho do host declarado no volume do compose, ou o caminho relativo está incorreto em relação ao diretório onde o docker compose é executado.
Solução: Execute ls -la ./traefik.yml no mesmo diretório do docker-compose.yml para confirmar que o arquivo existe. Use caminhos absolutos nos volumes para evitar ambiguidade: substitua ./traefik.yml por /home/usuario/traefik/traefik.yml. Crie o arquivo se ele não existir antes de subir o compose.

Sintoma: Traefik inicia mas retorna 404 para todas as requisições

Causa: Nenhum router corresponde ao host da requisição. Isso ocorre quando o Host() nas labels usa um domínio diferente do que está sendo acessado, ou quando o entrypoint da requisição não corresponde ao entrypoint declarado no router.
Solução: Acesse o dashboard em :8080/dashboard/#/http/routers e verifique a regra de cada router. Confirme que o domínio na label traefik.http.routers.nome.rule=Host() é exatamente igual ao domínio da requisição, incluindo ou excluindo o www. Para aceitar ambos, use Host(`exemplo.com`) || Host(`www.exemplo.com`).

Perguntas frequentes sobre Traefik não iniciando

Por que o Traefik não inicia mesmo com o docker-compose.yml correto?

O Traefik pode falhar ao iniciar por erros de sintaxe no arquivo traefik.yml, porta 80 ou 443 já ocupada por outro processo, ou permissão negada ao socket do Docker. Execute docker logs traefik para ver a mensagem exata e identifique qual recurso está bloqueado antes de reiniciar o container. Um docker-compose.yml sintaticamente correto não garante que os arquivos referenciados existam ou tenham as permissões certas.

Como verificar se o Traefik está realmente rodando no Docker?

Execute docker ps | grep traefik para ver se o container está com status Up. Se aparecer Exited, rode docker logs traefik --tail 50 para ler as últimas linhas do log e identificar o erro. O dashboard do Traefik na porta 8080 também confirma se o serviço está ativo — se a página carregar, o Traefik está operacional e o problema é de roteamento, não de inicialização.

O Traefik mostra "bind: address already in use" — como resolver?

Esse erro significa que a porta 80 ou 443 já está sendo usada por outro processo, como Apache ou Nginx rodando diretamente no host. Execute ss -tlnp | grep :80 para identificar o processo, pare-o com systemctl stop apache2 (ou nginx) e reinicie o container do Traefik. Se precisar manter o servidor web no host, considere migrar todos os serviços para Docker e deixar o Traefik como único ponto de entrada.

Como forçar o Traefik a renovar certificados Let's Encrypt?

Pare o container do Traefik, remova o arquivo acme.json com rm /etc/traefik/acme.json, recrie-o com permissão 600 (touch acme.json && chmod 600 acme.json) e reinicie o container. O Traefik solicitará novos certificados automaticamente na próxima inicialização. Atenção: remover o acme.json apaga todos os certificados armazenados — todos os domínios serão revalidados, o que pode levar alguns minutos.

Traefik não roteia para o container correto: como diagnosticar?

Verifique se o container de destino está na mesma rede Docker que o Traefik com docker network inspect nome_da_rede. Confirme se as labels do container estão corretas, especialmente traefik.http.routers.nome.rule com o Host correto. O dashboard do Traefik em :8080/dashboard mostra rotas ativas e erros de configuração em tempo real — é o recurso mais rápido para identificar labels mal formadas ou routers sem serviço associado.

Conclusão

• Sempre consulte os logs primeiro: docker logs traefik --tail 80 revela a causa exata em quase todos os casos de falha de inicialização.
• Verifique as três causas mais comuns em ordem: conflito de porta (use ss -tlnp), permissão do acme.json (deve ser 600) e sintaxe do traefik.yml (valide com Python ou yq antes de subir).
• Use o dashboard para roteamento: quando o Traefik inicia mas não roteia corretamente, o dashboard em :8080/dashboard é mais rápido que qualquer análise manual de logs para identificar labels incorretas ou redes desconectadas.

Leia também

• Entenda o Processo de Configuração de Limite de Upload no Webmail Roundcube em VPS Linux e Servidor Dedicado
• Guia para resolver erro de memória no WordPress: diagnóstico e ampliação
• Entenda o Processo de Configuração de Limite de Processos no Apache para VPS Linux e Servidor Dedicado

Precisa de ajuda com Traefik e containers Docker?

Configurar proxy reverso com Traefik em produção exige um ambiente estável com recursos dedicados e rede confiável. Um VPS Linux com acesso root completo permite ajustar portas, permissões e redes Docker sem restrições de ambiente compartilhado.

Conheça os planos de VPS da AviraHost e hospede seus containers com controle total