Multi-Agent Dev Hub - RUNBOOK¶

Guia operacional para deploy, configuração e troubleshooting.

📋 Pré-requisitos¶

Sistema¶

Ubuntu 20.04+ ou Debian 11+
Docker 20.10+
Docker Compose 1.29+
4GB RAM mínimo, 8GB recomendado
20GB espaço em disco

DNS e Domínio¶

Configure os seguintes registros DNS:

matrix.seudominio.com    A      SEU_IP_SERVIDOR
element.seudominio.com   A      SEU_IP_SERVIDOR
_matrix._tcp.seudominio.com SRV 10 0 8448 matrix.seudominio.com

Portas Necessárias¶

80 (HTTP - redireciona para HTTPS)
443 (HTTPS)
8448 (Matrix Federation)

🚀 Deploy Inicial¶

Etapa 1: Clonar e Configurar¶

cd /opt
git clone <repo> multiagent-dev-hub
cd multiagent-dev-hub/infra/core
cp .env.example .env

Edite .env com suas configurações:

nano .env

Variáveis obrigatórias: - MATRIX_DOMAIN - Ex: matrix.seudominio.com - MATRIX_SERVER_NAME - Ex: seudominio.com
- POSTGRES_PASSWORD - Senha forte do PostgreSQL - SYNAPSE_REGISTRATION_SHARED_SECRET - Gere com: openssl rand -hex 32 - SYNAPSE_MACAROON_SECRET_KEY - Gere com: openssl rand -hex 32 - LETSENCRYPT_EMAIL - Seu email para certificados SSL

Etapa 2: Gerar Configuração do Synapse¶

# Criar diretório de dados
mkdir -p synapse/data

# Gerar configuração inicial
docker run -it --rm \
  -v $(pwd)/synapse/data:/data \
  -e SYNAPSE_SERVER_NAME=seudominio.com \
  -e SYNAPSE_REPORT_STATS=no \
  matrixdotorg/synapse:latest generate

# Ajustar permissões
sudo chown -R 991:991 synapse/data

Etapa 3: Configurar Banco de Dados no Synapse¶

Edite synapse/data/homeserver.yaml:

database:
  name: psycopg2
  args:
    user: synapse
    password: SUA_SENHA_DO_ENV
    database: synapse
    host: synapse-db
    port: 5432
    cp_min: 5
    cp_max: 10

Ajuste também:

enable_registration: false  # Desabilitar registro público
registration_shared_secret: "SEU_SHARED_SECRET_DO_ENV"

# Listeners
listeners:
  - port: 8008
    tls: false
    type: http
    x_forwarded: true
    bind_addresses: ['::']

    resources:
      - names: [client, federation]
        compress: false

Etapa 4: Subir o Core¶

cd /opt/multiagent-dev-hub/infra/core
docker-compose up -d

# Verificar logs
docker-compose logs -f synapse

Aguarde ~30 segundos para Synapse inicializar.

Etapa 5: Criar Usuário Admin¶

# Registrar usuário admin
docker exec -it matrix-synapse register_new_matrix_user \
  -c /data/homeserver.yaml \
  -u admin \
  -p SUA_SENHA_ADMIN \
  --admin \
  http://localhost:8008

Etapa 6: Testar Acesso¶

Acesse: - Element Web: https://element.seudominio.com - Matrix API: https://matrix.seudominio.com/_matrix/client/versions

Login no Element com: - Usuário: @admin:seudominio.com - Senha: a que você definiu

🔗 Configurar Bridge Telegram¶

Criar Bot no Telegram¶

Abra o Telegram e procure por @BotFather
Envie /newbot
Escolha um nome e username
Copie o token fornecido

Obter API Credentials¶

Acesse https://my.telegram.org/apps
Crie uma aplicação
Copie API ID e API Hash

Configurar mautrix-telegram¶

cd /opt/multiagent-dev-hub/infra/core

# Atualizar .env com credenciais do Telegram
nano .env

Adicione:

TELEGRAM_API_ID=12345678
TELEGRAM_API_HASH=abcdef1234567890abcdef1234567890
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz

Gerar configuração do bridge:

docker-compose run --rm mautrix-telegram

# Editar config gerado
nano mautrix-telegram/config.yaml

Ajustes importantes em config.yaml:

homeserver:
  address: http://synapse:8008
  domain: seudominio.com

appservice:
  address: http://mautrix-telegram:29317
  hostname: mautrix-telegram
  port: 29317

  database: sqlite:////data/mautrix-telegram.db

  bot_username: telegrambot

telegram:
  api_id: SEU_API_ID
  api_hash: SEU_API_HASH
  bot_token: SEU_BOT_TOKEN

bridge:
  permissions:
    '@admin:seudominio.com': admin
    'seudominio.com': user

Registrar o Bridge no Synapse¶

# Copiar arquivo de registro
docker-compose exec mautrix-telegram cat /data/registration.yaml > /tmp/telegram-registration.yaml

# Copiar para Synapse
cp /tmp/telegram-registration.yaml synapse/data/telegram-registration.yaml

Edite synapse/data/homeserver.yaml:

app_service_config_files:
  - /data/telegram-registration.yaml

Reinicie:

docker-compose restart synapse mautrix-telegram

Conectar Telegram¶

No Element, envie mensagem para @telegrambot:seudominio.com
Digite login
Siga as instruções (enviar código de verificação)
Após login, seus chats do Telegram aparecerão como salas Matrix

Criar Bridge de Grupo¶

Adicione o bot no grupo do Telegram
No Element, crie uma sala
Convide @telegrambot:seudominio.com para a sala
Digite na sala: !tg bridge -chatid (para descobrir o ID do grupo)
Digite: !tg bridge -12345678 (substitua pelo ID do grupo)

🤖 Subir Orquestrador e Agentes¶

Configurar Registry DB¶

cd /opt/multiagent-dev-hub/infra/agents
cp .env.example .env
nano .env

Defina:

REGISTRY_POSTGRES_PASSWORD=senha-forte
REDIS_PASSWORD=outra-senha-forte
MATRIX_HOMESERVER=https://matrix.seudominio.com
MATRIX_BOT_USERNAME=orchestrator
MATRIX_BOT_PASSWORD=senha-do-bot
MATRIX_BOT_ACCESS_TOKEN=  # será gerado

Criar Bot do Orquestrador¶

# Registrar bot do orquestrador no Matrix
docker exec -it matrix-synapse register_new_matrix_user \
  -c /data/homeserver.yaml \
  -u orchestrator \
  -p SENHA_FORTE \
  http://localhost:8008

Obter Access Token¶

curl -X POST "https://matrix.seudominio.com/_matrix/client/r0/login" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "identifier": {
      "type": "m.id.user",
      "user": "orchestrator"
    },
    "password": "SENHA_DO_BOT"
  }'

Copie o access_token e adicione no .env:

MATRIX_BOT_ACCESS_TOKEN=syt_xxxxxxxxx

Subir Agentes¶

docker-compose up -d

# Verificar logs
docker-compose logs -f orchestrator-worker

📊 Frontend de Gestão¶

cd /opt/multiagent-dev-hub/frontend
docker-compose up -d

Acesse: http://localhost:8000

Login padrão: - User: admin - Pass: (ver .env)

🔧 Comandos Úteis¶

Ver logs¶

docker-compose logs -f [serviço]
docker-compose logs --tail=100 synapse

Restart serviços¶

docker-compose restart [serviço]
docker-compose restart synapse

Backup¶

PostgreSQL:

docker exec matrix-postgres pg_dump -U synapse synapse > backup-$(date +%Y%m%d).sql

Dados Synapse:

tar czf synapse-data-$(date +%Y%m%d).tar.gz synapse/data/

Restaurar Backup¶

docker exec -i matrix-postgres psql -U synapse synapse < backup-20260203.sql

🐛 Troubleshooting¶

Matrix não inicia¶

# Ver logs detalhados
docker-compose logs synapse | tail -100

# Verificar config
docker exec -it matrix-synapse cat /data/homeserver.yaml | grep -A 5 database

# Testar conexão DB
docker exec -it matrix-postgres psql -U synapse -c "SELECT version();"

Bridge não conecta¶

# Ver logs do bridge
docker-compose logs mautrix-telegram

# Verificar se registration está correto
docker exec -it matrix-synapse cat /data/telegram-registration.yaml

# Restart bridge
docker-compose restart mautrix-telegram

SSL/TLS problemas¶

# Ver logs Traefik
docker-compose logs traefik

# Verificar acme.json
ls -lh traefik/letsencrypt/acme.json

# Se acme.json estiver grande mas sem certificados, delete e restart
rm traefik/letsencrypt/acme.json
touch traefik/letsencrypt/acme.json
chmod 600 traefik/letsencrypt/acme.json
docker-compose restart traefik

Orquestrador não responde¶

# Logs do worker
docker-compose -f ../agents/docker-compose.yml logs orchestrator-worker

# Verificar se bot está online no Matrix
curl "https://matrix.seudominio.com/_matrix/client/r0/sync?access_token=SEU_TOKEN&timeout=0"

📈 Monitoramento¶

Health Checks¶

Matrix:

curl https://matrix.seudominio.com/health

Orquestrador API:

curl http://localhost:8001/health

Métricas¶

Ver docker stats para uso de recursos:

docker stats

🔒 Segurança¶

Recomendações¶

Firewall: Abra apenas portas 80, 443, 8448
Senhas Fortes: Use geradores para todas as senhas
Backups Regulares: Configure cron para backups diários
Updates: Mantenha imagens Docker atualizadas
Rate Limiting: Configure no Synapse (já incluído no homeserver.yaml padrão)

Desabilitar Registro Público¶

Em homeserver.yaml:

enable_registration: false
enable_registration_without_verification: false

📞 Suporte¶

Ver logs com timestamp:

docker-compose logs -f --timestamps

Exportar logs para análise:

docker-compose logs > debug-$(date +%Y%m%d-%H%M).log

Próximos passos: Ver ARCHITECTURE.md para entender a arquitetura completa.

Running Tests¶

Quick Test (Docker)¶

cd /opt/mundix

# Run all tests in isolated containers
./run_tests.sh

This will: 1. Build test containers 2. Start isolated Postgres + Redis 3. Run pytest with coverage 4. Generate HTML coverage report 5. Clean up containers

Manual Test (Local)¶

# 1. Start test database
docker run -d --name mundix-test-db \
  -e POSTGRES_USER=mundix_test \
  -e POSTGRES_PASSWORD=test \
  -e POSTGRES_DB=mundix_test \
  -p 5433:5432 postgres:16

# 2. Start test Redis
docker run -d --name mundix-test-redis \
  -p 6380:6379 redis:7-alpine

# 3. Set environment
export REGISTRY_POSTGRES_URL=postgresql://mundix_test:test@localhost:5433/mundix_test
export REDIS_URL=redis://localhost:6380/0
export ORCHESTRATOR_API_SECRET_KEY=test-secret-key-minimum-32-chars

# 4. Run tests
cd /opt/mundix/orchestrator
pytest tests/ -v --cov

# 5. Cleanup
docker rm -f mundix-test-db mundix-test-redis

Test Coverage¶

View coverage report:

cd /opt/mundix
firefox test-results/htmlcov/index.html  # or your browser

Target: 85%+ coverage on auth module

CI/CD Integration¶

# .github/workflows/test.yml
name: Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run tests
        run: |
          cd /opt/mundix
          docker-compose -f infra/agents/docker-compose.test.yml up --abort-on-container-exit

Token Cleanup Job¶

Manual Cleanup¶

Run cleanup job once:

docker exec -it mundix-orchestrator-worker \
  python3 worker/main.py cleanup

Output:

{
  "event": "refresh_token_cleanup_completed",
  "total_before": 1523,
  "total_after": 1021,
  "expired_deleted": 487,
  "revoked_deleted": 15,
  "retention_days": 30
}

Automatic Cleanup¶

Cleanup runs automatically every 6 hours when worker starts:

docker logs -f mundix-orchestrator-worker | grep cleanup

Configuration¶

Adjust cleanup frequency:

# infra/agents/.env
REFRESH_TOKEN_CLEANUP_INTERVAL_SECONDS=21600  # 6 hours
REFRESH_TOKEN_REVOKED_RETENTION_DAYS=30       # Keep revoked for 30 days

Monitoring¶

Check token table size:

docker exec -it mundix-postgres psql -U mundix -d agent_registry -c \
  "SELECT 
    COUNT(*) as total,
    COUNT(*) FILTER (WHERE expires_at < NOW()) as expired,
    COUNT(*) FILTER (WHERE revoked = TRUE) as revoked
   FROM refresh_tokens;"

Rate Limiting¶

Check Rate Limit Keys¶

# Connect to Redis
docker exec -it mundix-redis redis-cli

# List all rate limit keys
> KEYS rl:*

# Check specific key
> GET rl:auth:login:192.168.1.100:john
"3"

# Check TTL
> TTL rl:auth:login:192.168.1.100:john
55

Test Rate Limiting¶

# Test login rate limit (5/min)
for i in {1..6}; do
  echo "Attempt $i:"
  curl -X POST http://localhost:8001/auth/login \
    -d "username=test&password=wrong" \
    -i | grep -E "(HTTP|Retry-After)"
  sleep 1
done

# Expected: First 5 succeed (or 401), 6th returns 429

Monitor Rate Limits¶

# Count 429 errors in logs
docker logs mundix-orchestrator-api 2>&1 | grep -c "rate_limit_exceeded"

# View recent rate limit events
docker logs mundix-orchestrator-api 2>&1 | \
  grep "rate_limit" | tail -20 | jq .

Adjust Limits¶

# infra/agents/.env
RATE_LIMIT_LOGIN_MAX=5      # Max login attempts
RATE_LIMIT_LOGIN_WINDOW=60  # Per 60 seconds

RATE_LIMIT_REFRESH_MAX=10
RATE_LIMIT_REFRESH_WINDOW=60

RATE_LIMIT_REGISTER_MAX=3
RATE_LIMIT_REGISTER_WINDOW=60

Restart services after changes:

docker-compose -f infra/agents/docker-compose.yml restart orchestrator-api