orquestrador/DEPLOY_SERVIDOR.md

Deploy do Telegram Satellite no Servidor

Este guia considera o modelo operacional atual do projeto:

• MySQL para tools e base mock
• Redis para estado conversacional
• Vertex AI para o modelo
• Telegram como canal principal

1) Fluxo com Git

# maquina local
git add .
git commit -m "ajustes no orquestrador"
git push origin main

# servidor
cd /opt/orquestrador
git pull origin main

2) Preparacao do ambiente

cd /opt/orquestrador
python3 -m venv venv
source venv/bin/activate
pip install -U pip
pip install -r requirements.txt

3) Dependencias externas

Garanta antes da subida:

• MySQL acessivel pelo host configurado
• Redis acessivel pelo host configurado
• credencial valida do Vertex AI
• token do bot do Telegram

4) Configurar .env.prod

Exemplo minimo:

GOOGLE_PROJECT_ID=seu-projeto
GOOGLE_LOCATION=us-central1
VERTEX_MODEL_NAME=gemini-2.5-pro

ENVIRONMENT=production
DEBUG=false

DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASSWORD=sua_senha
DB_NAME=orquestrador_mock

MOCK_DB_HOST=127.0.0.1
MOCK_DB_PORT=3306
MOCK_DB_USER=root
MOCK_DB_PASSWORD=sua_senha
MOCK_DB_NAME=orquestrador_mock

AUTO_SEED_TOOLS=true
AUTO_SEED_MOCK=true
MOCK_SEED_ENABLED=true

CONVERSATION_STATE_BACKEND=redis
CONVERSATION_STATE_TTL_MINUTES=60
REDIS_URL=redis://127.0.0.1:6379/0
REDIS_KEY_PREFIX=orquestrador
REDIS_SOCKET_TIMEOUT_SECONDS=5

TELEGRAM_BOT_TOKEN=seu_token_aqui
TELEGRAM_POLLING_TIMEOUT=30
TELEGRAM_REQUEST_TIMEOUT=45

Observacoes:

• em producao, o satelite exige CONVERSATION_STATE_BACKEND=redis;
• use DEBUG=false ou DEBUG=true, sem valores livres como release.

5) Credencial do Vertex AI

Defina um dos formatos abaixo:

• GOOGLE_APPLICATION_CREDENTIALS=/opt/orquestrador/sa.json
• ou Application Default Credentials

A service account precisa de permissao de uso do Vertex AI, como roles/aiplatform.user.

6) Bootstrap manual inicial

Antes de ativar o servico, rode uma inicializacao manual para validar banco e seeds:

cd /opt/orquestrador
source venv/bin/activate
python -m app.db.bootstrap

7) Configurar systemd

Copie o template principal:

sudo cp deploy/systemd/orquestrador.service.example /etc/systemd/system/orquestrador.service
sudo nano /etc/systemd/system/orquestrador.service

Se quiser um atalho explicito para bootstrap manual via systemd, existe tambem o template:

sudo cp deploy/systemd/orquestrador-bootstrap.service.example /etc/systemd/system/orquestrador-bootstrap.service

Depois recarregue e inicie:

sudo systemctl daemon-reload
sudo systemctl enable --now orquestrador
sudo systemctl status orquestrador

Logs:

journalctl -u orquestrador -f

8) Validacao rapida

Checklist minimo:

• o servico sobe sem excecao
• o Redis responde
• o bot aparece online no Telegram
• uma mensagem simples recebe resposta

Teste funcional:

1. Abra o bot no Telegram.
2. Envie uma mensagem como Ola.
3. Envie uma mensagem operacional como Quero ver carros ate 50000 reais.
4. Verifique os logs do servico se necessario.

9) Atualizacao em producao

cd /opt/orquestrador
git pull origin main
source venv/bin/activate
pip install -r requirements.txt
# rode o bootstrap apenas quando houver mudanca de schema/seed
python -m app.db.bootstrap
sudo systemctl restart orquestrador
sudo systemctl status orquestrador