Traefik na VPS: como instalar o proxy reverso
Guia de Traefik na VPS: tag fixa, Compose em ordem, acme.json com permissão 600, DNS antes do certificado, staging, dashboard com basicAuth, risco do socket do Docker e erros comuns.
Por Redação Eleven Host · @robson.direitodigital · 6 de novembro de 2026 · 11 min de leitura

Capa da Redação Eleven Host para o guia: Traefik na VPS: como instalar o proxy reverso Arte: Eleven Host
Traefik na VPS é a forma de colocar um proxy reverso na frente dos seus sites e aplicativos, para atendê-los pelo mesmo servidor, com HTTPS automático pelo Let's Encrypt. Veja o Compose, o DNS, o teste em staging, o dashboard e os erros comuns.
Atualizado em 06/11/2026. Na data deste guia, a v3.7.17, de 30/10, é a versão estável marcada como Latest no GitHub do projeto e traz uma correção de segurança. A v3.8.0-rc.1 é pré-lançamento: não use. Confira a página de lançamentos. Os blocos marcados como exemplo são montados aqui: confira cada um no seu servidor antes de usar.
O que é um proxy reverso
Proxy reverso é como um porteiro: recebe os acessos que chegam à VPS e encaminha cada um para o site ou aplicativo certo, conforme o endereço digitado. Assim vários sites dividem o mesmo servidor, e o HTTPS é cuidado num lugar só.
Segundo o GitHub do projeto, o Traefik é um proxy reverso HTTP e balanceador de carga moderno, com licença MIT e imagem oficial no Docker. Segundo a documentação, ele descobre a configuração inspecionando a infraestrutura, aqui, os contêineres do Docker, e atualiza as rotas em tempo real, sem reiniciar. Se você ainda está escolhendo o servidor, o guia completo de servidor VPS explica o que é uma VPS e como comparar os planos.
Fixe a versão da imagem
Os guias da documentação usam traefik:v3.7. Aqui usamos traefik:v3.7.17, que existe no Docker Hub. Um exemplo da documentação usa traefik:latest; não copie. Recomendamos fixar a versão para evitar atualização surpresa, sabendo que quem fixa precisa atualizar à mão para receber correções.
A documentação de migração lista mudanças de sintaxe entre a v2 e a v3, como IPWhiteList, que virou IPAllowList. Na prática, um tutorial antigo com sintaxe da v2 pode não funcionar na v3.
Antes de começar
Você precisa de um domínio com acesso ao painel de DNS, de Docker com o plugin Compose e do htpasswd, que vem no pacote apache2-utils. Depois de adicionar o repositório apt da Docker, como manda a página oficial de instalação para Ubuntu, o Docker e o plugin Compose saem deste comando:
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Um exemplo de comando para o htpasswd, que você confere no seu servidor:
sudo apt install apache2-utils
DNS antes do certificado
Crie no painel de DNS um registro para cada nome que vai usar, como traefik.seudominio.com.br e app.seudominio.com.br, apontando para o IP da VPS, e espere o registro valer antes de subir o Traefik. Com o desafio por HTTP, o Let's Encrypt precisa alcançar a porta 80. O DNS gerenciado grátis na rede da Cloudflare para domínios registrados conosco fica no painel da área do cliente.
Dividir uma mesma VPS entre vários sites cabe no seu caso? Confira na loja o que cada plano inclui. Ver as VPS
Passo 1: pasta, acme.json e rede
Crie a pasta do projeto e, dentro dela, a pasta dos certificados. O arquivo acme.json precisa existir com a permissão 600 antes do primeiro up. Um exemplo de comando:
mkdir -p ~/traefik/letsencrypt
cd ~/traefik
touch letsencrypt/acme.json
chmod 600 letsencrypt/acme.json
Segundo a documentação do Traefik sobre certificados ACME, o arquivo JSON do armazenamento precisa do modo 600. O Traefik 3.7 mantém essa verificação e recusa arquivo com permissão aberta demais, com a mensagem permissions %o for %s are too open, please use 600.
A rede Docker proxy é criada pelo próprio Compose abaixo, quando você sobe o Traefik. Outro projeto só se liga a ela depois que o Traefik estiver no ar.
Passo 2: gerar a senha do dashboard
O dashboard fica atrás de autenticação básica. A página do middleware basicAuth mostra este comando, que pede a senha sem colocá-la na linha e duplica cada $ do hash, porque o Compose usa $$ para escrever um $ literal:
echo $(htpasswd -nB user) | sed -e s/\\$/\\$\\$/g
Troque user pelo nome de usuário que quiser. A saída tem a forma usuário:hash. Guarde essa linha: ela entra no Compose, no lugar de COLE_O_HASH_AQUI. A documentação aceita hashes MD5, SHA1 e BCrypt.
Passo 3: o docker-compose.yml
Um exemplo de Compose, montado a partir dos guias do Traefik e do Docker, com domínios fictícios. Troque o e-mail por um endereço real e os domínios pelos seus. O YAML depende da indentação, e ela pode sumir ao copiar daqui: confira linha a linha, com 2 espaços por nível. Salve em ~/traefik/docker-compose.yml:
services:
traefik:
image: traefik:v3.7.17
container_name: traefik
restart: unless-stopped
security_opt:
- no-new-privileges:true
networks:
- proxy
ports:
- "80:80"
- "443:443"
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
- ./letsencrypt:/letsencrypt
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"
- "--providers.docker=true"
- "--providers.docker.exposedbydefault=false"
- "--providers.docker.network=proxy"
- "--api.dashboard=true"
- "--api.insecure=false"
- "--log.level=INFO"
- "--certificatesresolvers.le.acme.email=voce@seudominio.com.br"
- "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"
- "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
# - "--certificatesresolvers.le.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory"
labels:
- "traefik.enable=true"
- "traefik.http.routers.dashboard.rule=Host(`traefik.seudominio.com.br`)"
- "traefik.http.routers.dashboard.entrypoints=websecure"
- "traefik.http.routers.dashboard.service=api@internal"
- "traefik.http.routers.dashboard.tls.certresolver=le"
- "traefik.http.middlewares.dashboard-auth.basicauth.users=COLE_O_HASH_AQUI"
- "traefik.http.routers.dashboard.middlewares=dashboard-auth@docker"
whoami:
image: traefik/whoami
container_name: whoami
restart: unless-stopped
networks:
- proxy
labels:
- "traefik.enable=true"
- "traefik.http.routers.whoami.rule=Host(`app.seudominio.com.br`)"
- "traefik.http.routers.whoami.entrypoints=websecure"
- "traefik.http.routers.whoami.tls.certresolver=le"
networks:
proxy:
name: proxy
O serviço whoami é uma aplicação de teste. Com exposedByDefault em false, o Traefik ignora o contêiner sem o label traefik.enable=true; o padrão da opção é true, que publicaria tudo.
Passo 4: testar em staging antes do certificado real
O Let's Encrypt recomenda testar no ambiente de staging antes da produção, e os navegadores não confiam nos certificados dele: o aviso de certificado inválido é esperado. Segundo a documentação do Traefik sobre ACME, a opção caServer aponta o Traefik para esse ambiente. No Compose acima, tire o # da linha do staging. O endereço é:
https://acme-staging-v02.api.letsencrypt.org/directory
Depois, suba e acompanhe os logs:
docker compose up -d
docker compose logs -f traefik
Na data deste guia, a página de limites do Let's Encrypt traz, para produção, até 5 certificados para o mesmo conjunto exato de nomes a cada 7 dias e até 5 falhas de autorização por nome, por conta e por hora. Esses números podem mudar: confira a página antes de contar com eles.
Com o staging funcionando, comente a linha de novo. O acme.json ainda guarda a conta e os certificados de teste, então recomendamos recomeçar com o arquivo vazio, o que apaga tudo o que está nele. Um exemplo de comando, para conferir no seu servidor, de dentro de ~/traefik:
docker compose down
rm letsencrypt/acme.json
touch letsencrypt/acme.json
chmod 600 letsencrypt/acme.json
docker compose up -d
Por padrão, a renovação dos certificados de 90 dias começa 30 dias antes do vencimento.
O dashboard e o risco da porta 8080
Não use api.insecure=true em produção. Segundo o quick start do Traefik, essa opção deixa o dashboard na porta 8080 sem autenticação e é só para desenvolvimento.
A referência da API diz que ligar API e dashboard em produção não é recomendado; se ligar, no mínimo com autenticação e autorização, e a porta da API não deve ficar pública. O Compose acima mantém api.insecure=false e expõe o dashboard por roteador com HTTPS e basicAuth. Recomendamos avaliar a opção usersFile do basicAuth, para não deixar o hash no label.
O socket do Docker é um ponto sensível
Para descobrir os contêineres, o Traefik lê o socket do Docker. A documentação do Traefik trata o acesso irrestrito à API do Docker como preocupação de segurança: se o Traefik for comprometido, o atacante pode chegar ao host. O daemon roda como root, salvo no modo Rootless, e só usuários confiáveis devem controlá-lo, segundo a Docker.
O Compose acima monta o socket com :ro, mas isso não resolve o risco. Entre as medidas que a documentação lista estão filtrar as requisições com o Docker Socket Proxy da Tecnativa, expor o socket por TCP ou SSH com certificado de cliente e isolar a rede.
Passo 5: subir o segundo serviço
No mesmo arquivo, o segundo serviço entra na rede proxy, com traefik.enable=true e uma regra própria. A documentação mostra, para o mesmo domínio com caminho, este label; depois de editar, rode docker compose up -d:
"traefik.http.routers.whoami-api.rule=Host(`whoami.docker.localhost`) && PathPrefix(`/api`)"
Um exemplo para outro projeto, em outra pasta, que só funciona com o Traefik já no ar: a rede é declarada como externa, e o Compose dá erro se ela não existir. A porta 80 do label é uma suposição: troque pela porta da aplicação real, que o Traefik precisa saber quando há mais de uma porta exposta.
services:
app2:
image: traefik/whoami
restart: unless-stopped
networks:
- proxy
labels:
- "traefik.enable=true"
- "traefik.http.routers.app2.rule=Host(`app2.seudominio.com.br`)"
- "traefik.http.routers.app2.entrypoints=websecure"
- "traefik.http.routers.app2.tls.certresolver=le"
- "traefik.http.services.app2.loadbalancer.server.port=80"
networks:
proxy:
external: true
Cada nome novo pede um registro de DNS e um certificado novo, e conta nos limites do Let's Encrypt. Para ver outros sistemas que podem ficar atrás do proxy, há o guia de Twenty CRM na VPS e o guia de ERPNext na VPS, o ERP da empresa.
Erros comuns
- 404: a requisição não casou com nenhum roteador. A rota é dinâmica, por isso não é 503. Desde a v3.7.3, um middleware basicAuth sem usuários falha ao montar, o roteador sai do ar e a resposta também é 404, não 401.
- 502: erro ao contatar o serviço de destino. Uma causa é a porta errada; declare-a no label
loadbalancer.server.port. - 503: o roteador casou, mas não há servidor pronto.
- Várias redes: em contêiner ligado a mais de uma rede, defina a rede certa, senão o Docker escolhe uma ao acaso.
- Field not found: propriedade desconhecida na configuração; procure o erro nos logs.
Sem SNI ou sem domínio correspondente, o Traefik usa o certificado padrão. Esse certificado é autoassinado e aparece com o nome TRAEFIK DEFAULT CERT. Na prática, ver esse nome no navegador indica que o certificado do seu domínio não foi aplicado; confira o DNS, se a porta 80 está alcançável e os logs.
Se o Nginx já ocupa a porta 80
Uma porta do servidor atende um programa por vez, então o Nginx na porta 80 impede o Docker de publicar a mesma porta para o Traefik. O -p 8080:80 do Docker mapeia a 8080 do host para a 80 do contêiner. No Traefik, o desafio por HTTP precisa da porta 80, o desafio por TLS precisa da 443, e o DNS-01 não depende de nenhuma das duas, mas depende do provedor de DNS.
As opções abaixo são ideias não testadas, para avaliar:
- Nginx na 80 e a 443 livre: o Traefik só na 443, com desafio por TLS; o redirecionamento de HTTP fica com o Nginx.
- Nginx na frente e o Traefik numa porta local: o desafio de certificado não chega direto ao Traefik; use DNS-01 ou deixe o HTTPS no Nginx.
- Migrar: o Traefik nas portas 80 e 443 e o Nginx como um serviço atrás dele.
Para onde levar o proxy
Neste guia, o proxy reverso roda no mesmo servidor dos sites que ele atende.
A VPS do proxy reverso está definida? Confira na loja o que cada plano inclui. Conhecer as VPS
Perguntas frequentes
O que é o Traefik?
Segundo o GitHub do projeto, é um proxy reverso HTTP e balanceador de carga moderno, de código aberto, com licença MIT.
Posso usar traefik:latest?
Recomendamos fixar a versão, como traefik:v3.7.17, para evitar atualização surpresa. Quem fixa precisa atualizar à mão.
Por que o acme.json precisa da permissão 600?
Segundo a documentação do Traefik sobre ACME, o arquivo precisa do modo 600. O Traefik 3.7 recusa o arquivo quando a permissão está aberta demais.
Posso ligar o dashboard com api.insecure=true?
Não em produção. Essa opção deixa o dashboard na porta 8080 sem autenticação e, segundo o quick start, é só para desenvolvimento.