🔧 Runbooks Operacionais - C-Suite
Este documento contém procedimentos operacionais para deploy, rollback, troubleshooting e manutenção de todos os apps do ecossistema C-Suite.
📋 Índice
- Pré-requisitos e Preparação
- Deploy
- Rollback
- Verificação Pós-Deploy
- Troubleshooting
- Manutenção
- Runbooks por App
🔧 Pré-requisitos e Preparação
Verificações Antes do Deploy
# 1. Verificar acesso ao Docker Swarm
docker node ls
# Deve mostrar pelo menos 1 manager node
# 2. Verificar rede overlay
docker network ls | grep superbot-swarm-network
# Se não existir, criar:
docker network create --driver overlay superbot-swarm-network
# 3. Verificar secrets do Docker Swarm
docker secret ls
# Deve mostrar: db_password, csuite_db_password (ou similar)
# 4. Verificar variáveis de ambiente
cd /home/ec2-user/enviroment/apps/c-suite
cat .env | grep -E "DB_HOST|DB_USER|DB_PASSWORD"
# Verificar se estão configuradas corretamente
# 5. Verificar acesso ao banco de dados
mysql -h vallery.catmgckfixum.sa-east-1.rds.amazonaws.com -u core -p
# Deve conectar sem erros
Criar Secrets (se necessário)
# Secret para senha do banco (4c, csuite-executive, csuite-sales-manager)
echo "sua_senha_real" | docker secret create db_password -
# Secret para senha do banco C-Suite (csuite-context, csuite-executive)
echo "sua_senha_real" | docker secret create csuite_db_password -
# Verificar secrets criados
docker secret ls
Preparar Imagens Docker
# Navegar para o diretório do app
cd /home/ec2-user/enviroment/apps/c-suite
# Build das imagens (exemplo para csuite-sales-manager)
cd csuite-sales-manager
docker build -t csuite-sales-manager-api:latest ./manager-api
docker build -t csuite-sales-decision-api:latest ./decision-api
docker build -t csuite-refresh-radar:latest ./context-jobs
# Verificar imagens
docker images | grep csuite
🚀 Deploy
Deploy Inicial (Primeira Vez)
1. Traefik (API Gateway)
cd /home/ec2-user/enviroment/apps/c-suite/4c/docker/stack
# Configurar email para Let's Encrypt
export LETSENCRYPT_EMAIL='seu-email@dominio.com'
# Deploy do Traefik
docker stack deploy -c traefik.yml traefik
# Verificar
docker service ls | grep traefik
docker service ps traefik_traefik
2. 4c (Córtex Comercial)
cd /home/ec2-user/enviroment/apps/c-suite/4c/docker/stack
# Deploy do stack 4c
docker stack deploy -c 4c.yml fourc
# Verificar serviços
docker service ls | grep fourc_
docker service ps fourc_decision-api
3. csuite-executive
cd /home/ec2-user/enviroment/apps/c-suite/csuite-executive
# Build da imagem (se necessário)
docker build -t csuite-executive-api:latest ./csuite-api
# Deploy (usar stack file se existir, ou docker-compose)
# Exemplo com docker-compose:
docker-compose -f docker-compose.prod.yml up -d
# Ou com Docker Swarm (se tiver stack file):
# docker stack deploy -c docker-stack.yml csuite-executive
4. 4c-suite (Orquestrador)
cd /home/ec2-user/enviroment/apps/c-suite/4c-suite
# Build da imagem
docker build -t 4c-suite:latest .
# Deploy (ajustar conforme stack file disponível)
# docker stack deploy -c docker-stack.yml 4c-suite
5. csuite-context
cd /home/ec2-user/enviroment/apps/c-suite/csuite-context/approot
# Build da imagem
docker build -t csuite-context-api:latest .
# Deploy
docker stack deploy -c docker-stack.yml csuite-context
6. csuite-sales-manager
cd /home/ec2-user/enviroment/apps/c-suite/csuite-sales-manager
# Build das imagens
docker build -t csuite-sales-manager-api:latest ./manager-api
docker build -t csuite-sales-decision-api:latest ./decision-api
docker build -t csuite-refresh-radar:latest ./context-jobs
# Deploy
docker stack deploy -c stack-sales-manager.yml csuite-sales-manager
Deploy de Atualização (Update)
Atualização com Rolling Update (Recomendado)
# 1. Build da nova imagem
docker build -t csuite-sales-manager-api:v2.0.0 ./manager-api
# 2. Atualizar tag latest
docker tag csuite-sales-manager-api:v2.0.0 csuite-sales-manager-api:latest
# 3. Forçar atualização do serviço (rolling update)
docker service update --force csuite-sales-manager_manager-api
# 4. Verificar atualização
docker service ps csuite-sales-manager_manager-api
# Deve mostrar nova task com status "Running"
Atualização com Redeploy do Stack
# 1. Fazer backup do stack atual
cp stack-sales-manager.yml stack-sales-manager.yml.backup
# 2. Atualizar o stack file (se necessário)
# 3. Redeploy
docker stack deploy -c stack-sales-manager.yml csuite-sales-manager
# 4. Verificar
docker service ls | grep csuite-sales-manager
⏪ Rollback
Rollback de Serviço Específico
# 1. Listar versões de imagens disponíveis
docker images | grep csuite-sales-manager-api
# 2. Reverter para versão anterior
docker service update \
--image csuite-sales-manager-api:v1.0.0 \
csuite-sales-manager_manager-api
# 3. Verificar rollback
docker service ps csuite-sales-manager_manager-api
Rollback Completo do Stack
# 1. Remover stack atual
docker stack rm csuite-sales-manager
# 2. Aguardar remoção completa
docker stack ls | grep csuite-sales-manager
# Aguardar até não aparecer mais
# 3. Redeploy com versão anterior
docker stack deploy -c stack-sales-manager.yml.backup csuite-sales-manager
# 4. Verificar
docker service ls | grep csuite-sales-manager
Rollback de Banco de Dados (Migrations)
⚠️ ATENÇÃO: Rollback de migrations requer cuidado especial.
# 1. Verificar migrations aplicadas
mysql -h vallery.catmgckfixum.sa-east-1.rds.amazonaws.com -u core -p
USE csuite;
SELECT * FROM schema_migrations ORDER BY version DESC LIMIT 5;
# 2. Reverter migration específica (se houver script de rollback)
# Exemplo:
mysql -h ... -u ... -p < migrations/rollback_001.sql
# 3. Atualizar tabela de migrations
DELETE FROM schema_migrations WHERE version = '001';
✅ Verificação Pós-Deploy
Checklist Geral
Execute este checklist após cada deploy:
# ✅ 1. Verificar serviços rodando
docker service ls
# Todos os serviços devem estar com 1/1 replicas
# ✅ 2. Verificar health checks
curl -s https://4c-decision.internut.com.br/health | jq
curl -s https://csuite.internut.com.br/health | jq
curl -s https://4c-suite.internut.com.br/health | jq
curl -s https://csuite-context.internut.com.br/health | jq
curl -s https://sales-manager.internut.com.br/health | jq
curl -s https://sales-decision.internut.com.br/health | jq
# ✅ 3. Verificar logs de erros
docker service logs --tail 50 csuite-sales-manager_manager-api | grep -i error
# ✅ 4. Verificar conectividade com banco
docker service logs --tail 20 csuite-sales-manager_manager-api | grep -i "connection\|database"
# ✅ 5. Verificar Traefik routing
curl -s https://sales-manager.internut.com.br/manager/today | jq
# ✅ 6. Verificar métricas (se Prometheus configurado)
curl -s http://localhost:9090/api/v1/targets | jq '.data.activeTargets[] | select(.health=="up")'
# ✅ 7. Verificar certificados SSL
echo | openssl s_client -connect sales-manager.internut.com.br:443 -servername sales-manager.internut.com.br 2>/dev/null | openssl x509 -noout -dates
Checklist por App
4c
# Health checks
curl -s https://4c-decision.internut.com.br/health
curl -s https://4c-feature.internut.com.br/health
curl -s https://4c-scoring.internut.com.br/health
# Testar decisão
curl -X POST https://4c-decision.internut.com.br/decide \
-H "Content-Type: application/json" \
-d '{"customer_id": 1, "org_id": 1}'
# Verificar métricas
curl -s http://localhost:9090/api/v1/query?query=fourc_decision_api_requests_total
csuite-executive
# Health check
curl -s https://csuite.internut.com.br/health
# Testar dashboard
curl -s https://csuite.internut.com.br/dashboard/summary/1 | jq
# Verificar agentes
curl -s https://csuite.internut.com.br/agents/1 | jq
4c-suite
# Health check
curl -s https://4c-suite.internut.com.br/health
# Testar status do organismo
curl -s https://4c-suite.internut.com.br/organismo/1/status | jq
csuite-context
# Health check
curl -s https://csuite-context.internut.com.br/health
# Testar eventos
curl -s "https://csuite-context.internut.com.br/api/csuite/events?org_id=1&limit=10" | jq
# Testar tendências
curl -s "https://csuite-context.internut.com.br/api/csuite/trends?org_id=1&limit=10" | jq
csuite-sales-manager
# Health checks
curl -s https://sales-manager.internut.com.br/health
curl -s https://sales-decision.internut.com.br/health
# Testar manager API
curl -s https://sales-manager.internut.com.br/manager/today | jq
# Testar decision API
curl -X POST https://sales-decision.internut.com.br/4c/decide \
-H "Content-Type: application/json" \
-d '{"revenda_id": 1}'
🔍 Troubleshooting
Problema: Serviço não inicia
Sintomas:
docker service ps csuite-sales-manager_manager-api
# Status: "Failed" ou "Rejected"
Diagnóstico:
# 1. Ver logs detalhados
docker service logs --tail 100 csuite-sales-manager_manager-api
# 2. Verificar eventos do serviço
docker service ps --no-trunc csuite-sales-manager_manager-api
# 3. Verificar recursos do node
docker node inspect self | jq '.[0].Description.Resources'
Soluções Comuns:
- Erro de imagem não encontrada: Fazer build da imagem antes do deploy
- Erro de secret não encontrado: Criar secret do Docker Swarm
- Erro de rede: Verificar se superbot-swarm-network existe
- Erro de memória: Verificar limites de recursos no stack file
Problema: Serviço reinicia constantemente
Sintomas:
docker service ps csuite-sales-manager_manager-api
# Múltiplas tasks com status "Shutdown" ou "Failed"
Diagnóstico:
# 1. Ver logs do último restart
docker service logs --tail 200 csuite-sales-manager_manager-api
# 2. Verificar health check
docker service inspect csuite-sales-manager_manager-api | jq '.[0].Spec.TaskTemplate.ContainerSpec.Healthcheck'
# 3. Testar health check manualmente
docker run --rm csuite-sales-manager-api:latest curl -f http://localhost:8000/health || echo "Health check falhou"
Soluções Comuns:
- Erro de conexão com banco: Verificar DB_HOST, DB_USER, DB_PASSWORD_FILE
- Erro de aplicação: Verificar logs para exceções Python
- Health check muito restritivo: Ajustar timeout/interval no stack file
Problema: Erro 502 Bad Gateway (Traefik)
Sintomas:
curl https://sales-manager.internut.com.br/health
# 502 Bad Gateway
Diagnóstico:
# 1. Verificar se serviço está rodando
docker service ls | grep sales-manager
# 2. Verificar logs do Traefik
docker service logs --tail 100 traefik_traefik | grep sales-manager
# 3. Verificar labels do serviço
docker service inspect csuite-sales-manager_manager-api | jq '.[0].Spec.TaskTemplate.ContainerSpec.Labels'
# 4. Verificar rede
docker network inspect superbot-swarm-network | jq '.[0].Containers'
Soluções Comuns:
- Serviço não está na rede: Verificar networks no stack file
- Porta incorreta: Verificar loadbalancer.server.port no label do Traefik
- Serviço não está saudável: Verificar health check do serviço
Problema: Erro de conexão com banco
Sintomas:
docker service logs csuite-sales-manager_manager-api | grep -i "can't connect\|operationalerror\|connection"
Diagnóstico:
# 1. Verificar variáveis de ambiente
docker service inspect csuite-sales-manager_manager-api | jq '.[0].Spec.TaskTemplate.ContainerSpec.Env'
# 2. Testar conexão do container
docker run --rm --network superbot-swarm-network \
-e DB_HOST=vallery.catmgckfixum.sa-east-1.rds.amazonaws.com \
-e DB_USER=core \
-e DB_PASSWORD_FILE=/run/secrets/db_password \
csuite-sales-manager-api:latest \
python -c "import MySQLdb; MySQLdb.connect(host='vallery.catmgckfixum.sa-east-1.rds.amazonaws.com', user='core', passwd=open('/run/secrets/db_password').read().strip())"
# 3. Verificar security groups do RDS
# (Verificar no console AWS se IP do servidor está autorizado)
Soluções Comuns:
- Secret não montado: Verificar secrets no stack file
- Host incorreto: Verificar DB_HOST no .env ou stack file
- Security group bloqueando: Autorizar IP do servidor no RDS
Problema: Certificado SSL não funciona
Sintomas:
curl https://sales-manager.internut.com.br/health
# SSL certificate problem
Diagnóstico:
# 1. Verificar logs do Traefik
docker service logs --tail 100 traefik_traefik | grep -i "certificate\|acme\|letsencrypt"
# 2. Verificar volume de certificados
docker volume ls | grep traefik-acme
# 3. Verificar labels do Traefik
docker service inspect traefik_traefik | jq '.[0].Spec.TaskTemplate.ContainerSpec.Labels' | grep -i tls
Soluções Comuns:
- Email não configurado: Verificar LETSENCRYPT_EMAIL no deploy do Traefik
- DNS não aponta para servidor: Verificar registros DNS
- Rate limit do Let's Encrypt: Aguardar ou usar staging
Problema: Performance degradada
Sintomas:
- Respostas lentas
- Timeouts
- Alta utilização de CPU/memória
Diagnóstico:
# 1. Verificar recursos dos containers
docker stats --no-stream
# 2. Verificar métricas do Prometheus (se configurado)
curl -s http://localhost:9090/api/v1/query?query=rate(container_cpu_usage_seconds_total[5m])
# 3. Verificar logs de lentidão
docker service logs --tail 500 csuite-sales-manager_manager-api | grep -i "slow\|timeout\|long"
# 4. Verificar queries lentas no banco
mysql -h ... -u ... -p -e "SHOW PROCESSLIST;" | grep -v Sleep
Soluções Comuns:
- Aumentar replicas: docker service scale csuite-sales-manager_manager-api=2
- Otimizar queries: Analisar slow query log do MySQL
- Aumentar recursos: Ajustar deploy.resources no stack file
- Verificar cache: Verificar se Redis está funcionando (se aplicável)
🔧 Manutenção
Atualização de Dependências
# 1. Atualizar requirements.txt
cd csuite-sales-manager/manager-api
pip-compile requirements.in # Se usar pip-tools
# Ou editar requirements.txt manualmente
# 2. Testar localmente
docker build -t csuite-sales-manager-api:test ./manager-api
docker run --rm csuite-sales-manager-api:test python -m pytest # Se houver testes
# 3. Deploy em staging primeiro
# 4. Deploy em produção após validação
Limpeza de Recursos
# 1. Remover imagens antigas
docker image prune -a --filter "until=168h" # Remove imagens não usadas há 7 dias
# 2. Remover containers parados
docker container prune
# 3. Remover volumes não usados
docker volume prune
# 4. Limpar logs (ajustar max-size no stack file)
# Logs são gerenciados automaticamente se configurado max-size/max-file
Backup
# 1. Backup do banco de dados
mysqldump -h vallery.catmgckfixum.sa-east-1.rds.amazonaws.com \
-u core -p \
--single-transaction \
--routines \
--triggers \
csuite > backup_csuite_$(date +%Y%m%d).sql
# 2. Backup de secrets (cuidado com segurança!)
docker secret ls > secrets_backup_$(date +%Y%m%d).txt
# 3. Backup de stack files
tar -czf stacks_backup_$(date +%Y%m%d).tar.gz */docker-stack.yml */stack-*.yml
Monitoramento
# 1. Verificar saúde geral
docker service ls
docker node ls
# 2. Verificar uso de recursos
docker stats --no-stream
# 3. Verificar logs recentes
docker service logs --tail 50 --since 10m csuite-sales-manager_manager-api
# 4. Verificar métricas (se Prometheus configurado)
# Acessar: https://prometheus.internut.com.br
# Acessar: https://grafana.internut.com.br
📱 Runbooks por App
4c
Stack: fourc
Arquivo: 4c/docker/stack/4c.yml
Deploy:
cd 4c/docker/stack
docker stack deploy -c 4c.yml fourc
Verificação:
docker service ls | grep fourc_
curl -s https://4c-decision.internut.com.br/health
Rollback:
docker service update --image 4c-decision-api:v1.0.0 fourc_decision-api
Documentação: 4c/docs/README_OPERACIONAL.md
csuite-executive
Stack: csuite-executive (ou docker-compose)
Deploy:
cd csuite-executive
docker build -t csuite-executive-api:latest ./csuite-api
docker stack deploy -c docker-stack.yml csuite-executive
# Ou: docker-compose -f docker-compose.prod.yml up -d
Verificação:
curl -s https://csuite.internut.com.br/health
curl -s https://csuite.internut.com.br/dashboard/summary/1
Rollback:
docker service update --image csuite-executive-api:v1.0.0 csuite-executive_csuite-api
4c-suite
Stack: 4c-suite
Deploy:
cd 4c-suite
docker build -t 4c-suite:latest .
docker stack deploy -c docker-stack.yml 4c-suite
Verificação:
curl -s https://4c-suite.internut.com.br/health
curl -s https://4c-suite.internut.com.br/organismo/1/status
csuite-context
Stack: csuite-context
Arquivo: csuite-context/approot/docker-stack.yml
Deploy:
cd csuite-context/approot
docker build -t csuite-context-api:latest .
docker stack deploy -c docker-stack.yml csuite-context
Verificação:
curl -s https://csuite-context.internut.com.br/health
curl -s "https://csuite-context.internut.com.br/api/csuite/events?org_id=1&limit=10"
Rollback:
docker service update --image csuite-context-api:v1.0.0 csuite-context_csuite-context-api
csuite-sales-manager
Stack: csuite-sales-manager
Arquivo: csuite-sales-manager/stack-sales-manager.yml
Deploy:
cd csuite-sales-manager
docker build -t csuite-sales-manager-api:latest ./manager-api
docker build -t csuite-sales-decision-api:latest ./decision-api
docker build -t csuite-refresh-radar:latest ./context-jobs
docker stack deploy -c stack-sales-manager.yml csuite-sales-manager
Verificação:
curl -s https://sales-manager.internut.com.br/health
curl -s https://sales-decision.internut.com.br/health
curl -s https://sales-manager.internut.com.br/manager/today
Rollback:
docker service update --image csuite-sales-manager-api:v1.0.0 csuite-sales-manager_manager-api
docker service update --image csuite-sales-decision-api:v1.0.0 csuite-sales-manager_decision-api
Executar Job de Refresh:
# Escalar job para 1 replica (executa uma vez e termina)
docker service scale csuite-sales-manager_refresh-radar-job=1
# Verificar execução
docker service logs --tail 50 csuite-sales-manager_refresh-radar-job
# Voltar para 0 replicas após execução
docker service scale csuite-sales-manager_refresh-radar-job=0
📚 Referências
- SETUP.md - Guia de setup inicial
- API_DOCUMENTATION.md - Documentação de APIs
- GLOSSARIO.md - Glossário de termos
- 4c/docs/README_OPERACIONAL.md - Runbook específico do 4c
🆘 Contatos de Emergência
- On-call Engineer: [definir]
- Database Admin: [definir]
- Infrastructure Team: [definir]
Última atualização: 2025-12-01