Proxy Reverso para Instância Mastodon com Caddy: Notas de Configuração

Executar uma instância Mastodon requer um proxy reverso para lidar com terminação TLS, roteamento de requisições e suporte WebSocket. O Caddy é um servidor web moderno que simplifica esse processo com HTTPS automático e sintaxe de configuração limpa. Muitos administradores escolhem o Caddy porque elimina a necessidade de gerenciar certificados SSL manualmente. Este artigo explica as principais configurações necessárias para configurar o Caddy como proxy reverso para uma instância Mastodon, incluindo suporte WebSocket, limites de tamanho do corpo da requisição e cabeçalhos de segurança.

Por que o Mastodon Precisa de um Proxy Reverso

Mastodon é uma aplicação Ruby on Rails que executa um servidor web interno em uma porta não privilegiada. Esse servidor não foi projetado para lidar diretamente com tráfego público por vários motivos. Primeiro, ele não possui suporte TLS, o que significa que todo o tráfego seria não criptografado. Segundo, ele não consegue servir arquivos estáticos com a mesma eficiência de um servidor web dedicado. Terceiro, o Mastodon usa conexões WebSocket para streaming em tempo real das timelines, que exigem conexões persistentes que um proxy reverso pode gerenciar.

O Caddy provisiona e renova automaticamente certificados Let’s Encrypt, tornando a configuração TLS trivial. Ele também lida com HTTP/2 e HTTP/3, compacta respostas e adiciona cabeçalhos de segurança. Ao colocar o Caddy na frente do Mastodon, você transfere todas essas tarefas do servidor de aplicação, permitindo que ele se concentre em entregar conteúdo.

Configuração Essencial do Caddy para Mastodon

O núcleo da configuração é a diretiva reverse_proxy dentro de um bloco de site. Abaixo está um exemplo funcional mínimo. Substitua example.com pelo seu domínio real e localhost:3000 pelo endereço do processo web do Mastodon, se diferente.

1. Configure o bloco do site
   Crie uma entrada no Caddyfile para seu domínio. O Caddy obterá automaticamente um certificado TLS na primeira requisição.
   example.com {
reverse_proxy localhost:3000
}
2. Adicione suporte WebSocket
   O Mastodon usa WebSockets para a API de streaming. Sem isso, funcionalidades como atualizações de timeline em tempo real não funcionarão. O Caddy lida com upgrades WebSocket automaticamente ao usar reverse_proxy, mas você deve garantir que o endereço do backend esteja correto. O servidor de streaming geralmente roda na porta 4000. Adicione um proxy reverso separado para o endpoint de streaming.
   example.com {
reverse_proxy /api/v1/streaming/ localhost:4000
reverse_proxy localhost:3000
}
3. Encaminhe o IP do cliente
   O Mastodon precisa saber o IP original do visitante para limitação de taxa e registro de logs. Adicione a diretiva trusted_proxies para informar ao Caddy que ele deve confiar em si mesmo e passar o IP real por meio de cabeçalhos.
   example.com {
trusted_proxies private_ranges
reverse_proxy localhost:3000
}
4. Aumente o tamanho do corpo da requisição
   O Mastodon permite uploads de mídia de até 8 MB por padrão, mas administradores podem aumentar esse limite. O padrão do Caddy é 1 MB. Defina o tamanho máximo do corpo para pelo menos 10 MB para evitar falhas de upload.
   example.com {
request_body /max_size 10MB
reverse_proxy localhost:3000
}
5. Adicione cabeçalhos de segurança
   Cabeçalhos de segurança protegem contra ataques web comuns. Os seguintes cabeçalhos são recomendados para instâncias Mastodon.
   example.com {
header / {
X-Content-Type-Options "nosniff"
X-Frame-Options "DENY"
X-XSS-Protection "1; mode=block"
Referrer-Policy "strict-origin-when-cross-origin"
}
reverse_proxy localhost:3000
}
6. Ative a compressão gzip
   A compressão reduz a largura de banda e acelera o carregamento das páginas. O Caddy ativa gzip por padrão, mas você pode configurá-lo explicitamente se necessário.
   example.com {
encode gzip
reverse_proxy localhost:3000
}

Erros Comuns de Configuração

Conexões WebSocket falham após alguns segundos

Se as conexões WebSocket caírem repetidamente, provavelmente o proxy reverso para o endpoint de streaming está ausente ou mal configurado. Certifique-se de que o caminho /api/v1/streaming/* esteja roteado para a porta 4000. Verifique também se o Caddy não está aplicando timeouts muito curtos. Adicione reverse_proxy /api/v1/streaming/* localhost:4000 antes da linha de proxy reverso geral. O Caddy avalia as rotas em ordem, então o caminho de streaming deve corresponder primeiro.

Uploads de mídia retornam 413 Request Entity Too Large

Esse erro indica que o limite de tamanho do corpo da requisição está muito baixo. O padrão do Caddy é 1 MB, enquanto o padrão do Mastodon é 8 MB. Aumente o limite para pelo menos 10 MB usando a diretiva request_body /max_size. Se você aumentou ainda mais o limite do Mastodon, defina o limite do Caddy para corresponder.

IP do cliente aparece como 127.0.0.1 nos logs

Sem a diretiva trusted_proxies, o Caddy não encaminha o IP original do cliente. Adicione trusted_proxies private_ranges ao seu Caddyfile. Isso informa ao Caddy para confiar em IPs de faixas privadas e passar o IP real por meio do cabeçalho X-Forwarded-For. O Mastodon também deve ser configurado para ler esse cabeçalho. Em .env.production, defina TRUSTED_PROXY_IPS=127.0.0.1 ou o IP do seu contêiner Caddy.

Item	Nginx	Caddy
Descrição	Proxy reverso tradicional com gerenciamento manual de certificados SSL	Proxy reverso moderno com HTTPS automático e configuração mais simples
Renovação de certificado SSL	Manual ou via cron job do certbot	Automática via Let’s Encrypt
Sintaxe de configuração	Baseada em diretivas com muitos blocos aninhados	Diretivas concisas e declarativas
Suporte WebSocket	Requer diretivas explícitas proxy_set_header Upgrade e Connection	Automático ao usar reverse_proxy
Limite de tamanho do corpo da requisição	client_max_body_size 10M	request_body /max_size 10MB
Encaminhamento de IP do cliente	proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for	trusted_proxies private_ranges

Com as etapas de configuração acima, sua instância Mastodon funcionará de forma eficiente por trás do Caddy. O recurso TLS automático elimina preocupações com renovação de certificados, e os cabeçalhos de segurança protegem contra vulnerabilidades comuns. Para verificar se tudo está funcionando, confira os logs do Mastodon para o IP correto do cliente e teste uploads de mídia de vários tamanhos. Se precisar escalar, considere adicionar o balanceamento de carga integrado do Caddy com múltiplos processos web do Mastodon.