Guia de Deploy — Fundações da Infraestrutura¶

Última atualização: Abril 2026
Autor: Arthur Jahn (Tech Lead)

Este guia descreve o processo completo para provisionar do zero a infraestrutura base do Sinapses IA: proxy reverso (Caddy), monitoramento (Zabbix), documentação (MkDocs) e registry privado Docker.

Pré-requisitos¶

Em todos os VMs¶

# Docker Engine
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker

# Docker Compose (plugin v2)
docker compose version   # deve mostrar v2.x

# Git
sudo apt-get install -y git

Firewall (UFW)¶

Configure antes de subir qualquer serviço.

vm-assurance-llm (proxy + monitoramento):

sudo ufw allow 22/tcp          # SSH
sudo ufw allow 80/tcp          # HTTP (ACME challenge)
sudo ufw allow 443/tcp         # HTTPS
sudo ufw allow 443/udp         # HTTP/3 (QUIC)
sudo ufw allow 10051/tcp       # Zabbix Server (agentes externos)
sudo ufw default deny incoming
sudo ufw enable

vm-assurance-llm-sandbox, vm-assurance-llm2, vm-assurance-llm-about:

sudo ufw allow 22/tcp
sudo ufw default deny incoming
sudo ufw enable

Etapa 1 — DNS¶

Configure os registros A no seu provedor DNS antes de iniciar o Caddy. O Caddy precisa resolver os domínios para emitir certificados Let's Encrypt.

Registro	Tipo	Valor
`*.sinapsesia.com.br`	A	`172.174.236.146`
`*.hm.sinapsesia.com.br`	A	`172.174.236.146`

Aguardar propagação

Verifique a propagação antes de prosseguir:

dig +short zabbix.sinapsesia.com.br
dig +short docs.sinapsesia.com.br
# Ambos devem retornar 172.174.236.146

Etapa 2 — Configurar acesso ao repositório (Deploy Key)¶

O repositório infra é privado. A abordagem recomendada é uma deploy key SSH com acesso somente-leitura — nenhuma credencial pessoal é armazenada nos VMs e git pull funciona sem interação manual.

2.1 — Gerar o par de chaves (na sua máquina local, uma única vez)¶

ssh-keygen -t ed25519 -C "infra-deploy" -f ~/.ssh/infra_deploy_key -N ""

Dois arquivos serão criados: - ~/.ssh/infra_deploy_key — chave privada (nunca compartilhar) - ~/.ssh/infra_deploy_key.pub — chave pública (será registrada no repositório)

2.2 — Adicionar a chave pública ao repositório¶

No GitHub: Settings → Deploy keys → Add deploy key

Title: infra-deploy
Key: conteúdo de ~/.ssh/infra_deploy_key.pub
Allow write access: ❌ (somente leitura)

2.3 — Distribuir a chave privada para cada VM¶

# Substituir <VM_IP> e <VM_USER> conforme cada máquina
VM_IP=<VM_IP>
VM_USER=llmadmin

scp -i llm_rsa.pem ~/.ssh/infra_deploy_key ${VM_USER}@${VM_IP}:~/.ssh/infra_deploy_key
ssh -i llm_rsa.pem ${VM_USER}@${VM_IP} "chmod 600 ~/.ssh/infra_deploy_key"

Repita para os 4 VMs.

2.4 — Configurar SSH em cada VM¶

Execute dentro de cada VM:

cat >> ~/.ssh/config << 'EOF'
Host github.com
  IdentityFile ~/.ssh/infra_deploy_key
  IdentitiesOnly yes
EOF
chmod 600 ~/.ssh/config

# Verificar conectividade
ssh -T git@github.com
# Esperado: "Hi <org>/infra! You've successfully authenticated..."

Etapa 3 — Clonar o repositório em todos os VMs¶

Com a deploy key configurada, execute em cada um dos 4 VMs:

sudo git clone git@github.com:<org>/infra.git /opt/infra
sudo chown -R $USER:$USER /opt/infra

Atualizações futuras

Para aplicar mudanças do repositório em um VM:

cd /opt/infra && git pull
# Re-rodar o setup se necessário
./vm-llm/setup.sh   # ou o script do VM correspondente

Etapa 4 — Configurar `vm-assurance-llm`¶

Este é o VM central. Deve ser configurado primeiro.

4.1 — Preencher variáveis de ambiente¶

cd /opt/infra/vm-llm
cp .env.example .env
nano .env

Preencher:

ZABBIX_DB_PASSWORD=<senha_segura>
ZABBIX_ROOT_PASSWORD=<senha_root_segura>
REGISTRY_USER=admin
REGISTRY_PASSWORD=<senha_registry>

Gerando senhas seguras

openssl rand -base64 32

4.2 — Executar setup¶

chmod +x setup.sh
./setup.sh

O script realiza automaticamente:

Cria diretórios de dados (data/, auth/)
Gera auth/htpasswd com credenciais bcrypt para o registry
Executa docker compose pull + docker compose up -d

4.3 — Verificar serviços¶

docker compose ps

Saída esperada (todos healthy ou running):

NAME            STATUS
caddy           running
mkdocs          running
registry        running
zabbix-agent    running
zabbix-db       healthy
zabbix-server   running
zabbix-web      running (health: starting)

Zabbix Web demora ~60s para inicializar

O zabbix-web aguarda o banco inicializar antes de ficar pronto. Aguarde 1-2 minutos.

4.4 — Verificar certificados TLS¶

Acesse os domínios — o Caddy emite os certificados na primeira requisição:

curl -I https://zabbix.sinapsesia.com.br
curl -I https://docs.sinapsesia.com.br
curl -I https://registry.sinapsesia.com.br/v2/
# /v2/ retorna 401 — esperado (registry funcionando e autenticando)

4.5 — Verificar logs do Caddy¶

docker compose logs -f caddy

Procure por linhas como:

... certificate obtained successfully ...
... serving ...

Etapa 5 — Configurar VMs de aplicação¶

Execute em cada VM restante de forma independente.

`vm-assurance-llm-sandbox`¶

cd /opt/infra/vm-sandbox
cp .env.example .env
nano .env
# Preencher ZABBIX_SERVER_HOST com o IP privado de vm-assurance-llm
# Preencher REGISTRY_USER e REGISTRY_PASSWORD
chmod +x setup.sh
./setup.sh

`vm-assurance-llm2`¶

cd /opt/infra/vm-llm2
cp .env.example .env
nano .env
chmod +x setup.sh
./setup.sh

`vm-assurance-llm-about`¶

cd /opt/infra/vm-about
cp .env.example .env
nano .env
chmod +x setup.sh
./setup.sh

IP privado do Zabbix Server

O ZABBIX_SERVER_HOST deve ser o IP privado (VNet) de vm-assurance-llm, não o IP público. Consulte o portal Azure em Networking > Private IP.

Etapa 6 — Configurar Zabbix¶

6.1 — Primeiro acesso¶

Acesse https://zabbix.sinapsesia.com.br

Usuário: Admin
Senha: zabbix (padrão — alterar imediatamente)

6.2 — Cadastrar hosts monitorados¶

Em Configuration → Hosts → Create host, cadastrar cada VM:

Host name	IP do agente	Porta
`vm-assurance-llm`	`127.0.0.1` (via Docker network)	`10050`
`vm-assurance-llm-sandbox`	IP privado do VM	`10050`
`vm-assurance-llm2`	IP privado do VM	`10050`
`vm-assurance-llm-about`	IP privado do VM	`10050`

Aplicar o template Linux by Zabbix agent a cada host.

6.3 — Alterar senha padrão¶

Em User settings → Profile → Change password.

Etapa 7 — Registrar imagem de teste no registry¶

Valide que o registry está funcionando corretamente:

# Em vm-assurance-llm (ou qualquer VM que já fez setup.sh)
docker pull hello-world
docker tag hello-world registry.sinapsesia.com.br/hello-world:test
docker push registry.sinapsesia.com.br/hello-world:test

# Verificar
curl -u admin:<REGISTRY_PASSWORD> \
  https://registry.sinapsesia.com.br/v2/_catalog
# Deve retornar: {"repositories":["hello-world"]}

Etapa 8 — Deploy de aplicação homolog (exemplo)¶

Após as fundações estarem prontas, o processo para subir uma aplicação é:

# 1. No vm-assurance-llm: adicionar rota ao Caddyfile
nano /opt/infra/vm-llm/Caddyfile
# Descomentar / adicionar o bloco para analyze.hm.sinapsesia.com.br

# 2. Recarregar Caddy (sem downtime)
docker exec caddy caddy reload --config /etc/caddy/Caddyfile

# 3. No vm-assurance-llm-sandbox: subir a app
cd /opt/infra/vm-sandbox/apps/sinapses-hm
cp .env.example .env
nano .env   # ajustar IMAGE_TAG
docker compose up -d

Verificação Final¶

Check	Comando
Todos os serviços do vm-llm rodando	`docker compose -f /opt/infra/vm-llm/docker-compose.yml ps`
Zabbix Agent conectado ao servidor	`docker logs zabbix-agent 2>&1 \\| grep -i "active checks"`
TLS válido em todos os domínios	`curl -sI https://docs.sinapsesia.com.br \\| grep HTTP`
Registry autenticando	`curl -u admin:<PASS> https://registry.sinapsesia.com.br/v2/_catalog`
MkDocs acessível	`curl -sI https://docs.sinapsesia.com.br \\| grep HTTP`

Troubleshooting Rápido¶

Certificado TLS não emitido¶

# Verificar se porta 80 está acessível externamente
curl -v http://docs.sinapsesia.com.br/.well-known/acme-challenge/test

# Verificar logs do Caddy
docker logs caddy 2>&1 | grep -i "acme\|certificate\|error"

Zabbix Agent não conecta ao servidor¶

# Verificar variável de ambiente no container
docker exec zabbix-agent env | grep ZBX_SERVER

# Testar conectividade TCP para o Zabbix server (port 10051)
nc -zv <ZABBIX_SERVER_HOST> 10051

Registry retorna 500 ou não inicia¶

# Verificar se htpasswd foi gerado
ls -la /opt/infra/vm-llm/auth/

# Regenerar (re-rodar setup.sh é seguro)
cd /opt/infra/vm-llm && ./setup.sh

Manutenção¶

Atualizar configuração do Caddy (adicionar domínio)¶

nano /opt/infra/vm-llm/Caddyfile
docker exec caddy caddy reload --config /etc/caddy/Caddyfile

Atualizar imagens¶

cd /opt/infra/vm-llm
./setup.sh   # faz pull + recria containers atualizados

Backup¶

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

# Banco do Zabbix
docker exec zabbix-db mysqldump -u root -p<ROOT_PASSWORD> zabbix \
  > /backup/zabbix-$(date +%Y%m%d).sql

Confidencial — Assurance IT / Sinapses IA