Certificados e Domínios — Sinapses IA¶

Projeto: Sinapses IA — Gestão de Certificados com Caddy
Data: Abril 2026
Autor: Arthur Jahn (Tech Lead)
Status: Versão 1.0

1. Visão Geral¶

O Caddy gerencia todos os certificados SSL/TLS de forma automática via Let's Encrypt. Não há renovação manual — o Caddy solicita, armazena e renova certificados com 30 dias de antecedência.

Características:

Automático — sem intervenção manual
Gratuito — Let's Encrypt
Por domínio — um certificado por site block (sem wildcard TLS)
Centralizado — todos os certs gerenciados em vm-assurance-llm

2. Estratégia de Domínios¶

Convenção de Nomeação¶

{app}.{env}.sinapsesia.com.br

Padrão	Exemplo	Ambiente
`{app}.sinapsesia.com.br`	`recruit.sinapsesia.com.br`	Produção
`{app}.hm.sinapsesia.com.br`	`recruit.hm.sinapsesia.com.br`	Homologação
`{app}.dev.sinapsesia.com.br`	`recruit.dev.sinapsesia.com.br`	Desenvolvimento

Domínios de Infraestrutura¶

Domínio	Serviço
`zabbix.sinapsesia.com.br`	Monitoramento Zabbix
`docs.sinapsesia.com.br`	Documentação MkDocs
`registry.sinapsesia.com.br`	Registry Docker privado

Configuração de DNS¶

Todos os domínios apontam para o IP público de vm-assurance-llm:

*.sinapsesia.com.br     A   172.174.236.146
*.hm.sinapsesia.com.br  A   172.174.236.146

Wildcard DNS ≠ Wildcard TLS

O wildcard é apenas no DNS. Cada domínio no Caddyfile obtém seu próprio certificado via ACME HTTP-01 — não é necessário DNS challenge.

3. Fluxo de Certificação (ACME HTTP-01)¶

1. Nova requisição chega em Caddy para um domínio sem certificado
2. Caddy solicita certificado ao Let's Encrypt
3. Let's Encrypt envia desafio: GET http://{domínio}/.well-known/acme-challenge/{token}
4. Caddy responde ao desafio (porta 80 deve estar acessível)
5. Certificado emitido e armazenado em /data/caddy/
6. Renovação automática 30 dias antes do vencimento

Porta 80 obrigatória

A porta 80 (HTTP) deve estar acessível publicamente para que o ACME HTTP-01 funcione. O Caddy redireciona automaticamente HTTP → HTTPS após a validação.

4. Armazenamento¶

Os certificados ficam no volume Docker nomeado caddy_data, montado em /data no container Caddy. Este volume é persistente entre reinicializações.

# Verificar certificados armazenados
docker exec caddy caddy list-certs

# Verificar expiração de um domínio
echo | openssl s_client -connect zabbix.sinapsesia.com.br:443 2>/dev/null \
  | openssl x509 -noout -dates

5. Procedimentos Operacionais¶

Inicializar vm-assurance-llm¶

cd /opt/infra/vm-llm
cp .env.example .env        # preencher senhas
chmod +x setup.sh
./setup.sh                  # gera htpasswd, cria dirs, sobe compose

Adicionar novo domínio homolog¶

Editar Caddyfile em /opt/infra/vm-llm/Caddyfile:

analyze.hm.sinapsesia.com.br {
  reverse_proxy <IP_PRIVADO_VM_SANDBOX>:3000
}

Recarregar Caddy sem downtime:

docker exec caddy caddy reload --config /etc/caddy/Caddyfile

Forçar renovação de certificado¶

docker exec caddy caddy renew --force

Backup de certificados¶

# Backup do volume caddy_data
docker run --rm \
  -v caddy_data:/data \
  -v /backup:/backup \
  alpine tar czf /backup/caddy-data-$(date +%Y%m%d).tar.gz /data

# Restaurar
docker run --rm \
  -v caddy_data:/data \
  -v /backup:/backup \
  alpine tar xzf /backup/caddy-data-20260410.tar.gz -C /
docker compose restart caddy

6. Troubleshooting¶

Certificado não emitido¶

Sintomas: Erro SSL ao acessar o domínio, aviso de certificado inválido.

Verificações:

# Porta 80 acessível?
curl -v http://meu-dominio.sinapsesia.com.br

# DNS aponta para o IP correto?
dig +short meu-dominio.sinapsesia.com.br

# Logs do Caddy
docker compose -f /opt/infra/vm-llm/docker-compose.yml logs caddy | grep -i acme

Limite do Let's Encrypt: 5 certificados por domínio por semana. Para testes, usar staging:

{
  email admin@sinapsesia.com.br
  acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}

Erro 502 Bad Gateway¶

Causa: Serviço backend não está respondendo.

# Verificar se o serviço está rodando
docker compose ps

# Testar conectividade do Caddy ao backend
docker exec caddy wget -qO- http://zabbix-web:8080

# Verificar logs
docker compose logs caddy | grep -i error

HTTP não redireciona para HTTPS¶

# Verificar Caddyfile
docker exec caddy cat /etc/caddy/Caddyfile

# Recarregar configuração
docker exec caddy caddy reload --config /etc/caddy/Caddyfile

7. Changelog¶

Versão	Data	Descrição
1.0	Abril 2026	Documentação inicial

Confidencial — Assurance IT