From 72d8c6d7326d03f060e1457a238ba0e53cb8eae0 Mon Sep 17 00:00:00 2001 From: marco Date: Sun, 16 Aug 2026 20:46:09 -0300 Subject: [PATCH] docs(deploy): add comprehensive VPS deployment guide --- DEPLOY_VPS.md | 366 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 366 insertions(+) create mode 100644 DEPLOY_VPS.md diff --git a/DEPLOY_VPS.md b/DEPLOY_VPS.md new file mode 100644 index 0000000..7f03b90 --- /dev/null +++ b/DEPLOY_VPS.md @@ -0,0 +1,366 @@ +# Deploy em VPS - ThorAgentIA + +Guia completo para rodar o ThorAgentIA automaticamente em um servidor VPS Linux (Debian/Ubuntu). + +--- + +## Pré-requisitos + +- Acesso SSH ao servidor VPS +- Python 3.10+ instalado +- Git (opcional, para clonar o repositório) +- Sudo/root configurado + +--- + +## Passo 1: Preparar o Servidor + +```bash +# Atualizar pacotes +sudo apt update && sudo apt upgrade -y + +# Instalar dependências básicas +sudo apt install -y python3 python3-venv python3-pip git curl + +# Verificar versão do Python +python3 --version +``` + +--- + +## Passo 2: Transferir o Projeto para o VPS + +### Opção A: Via Git (recomendado) + +```bash +# Clonar o repositório +git clone /opt/thoragentia +cd /opt/thoragentia/app +``` + +### Opção B: Via SCP/SFTP + +```bash +# No seu computador local +scp -r app/ usuario@vps:/opt/thoragentia/ +``` + +### Opção C: Via rsync + +```bash +rsync -avz app/ usuario@vps:/opt/thoragentia/app/ +``` + +--- + +## Passo 3: Configurar o Ambiente + +```bash +cd /opt/thoragentia/app + +# Dar permissão de execução ao script +chmod +x iniciar.sh + +# Executar o script de inicialização +./iniciar.sh +``` + +O script irá: +- Criar o ambiente virtual +- Instalar dependências +- Preparar o sistema + +--- + +## Passo 4: Configurar Variáveis de Ambiente + +```bash +# Criar/editar o arquivo .env +nano /opt/thoragentia/app/.env +``` + +Preencher com: +```env +TELEGRAM_BOT_TOKEN=seu_token +TELEGRAM_CHAT_ID=seu_chat_id +INTERVAL_MINUTES=60 +START_HOUR=7 +END_HOUR=22 +DAYS_OF_WEEK=1,2,3,4,5,6,7 +TOPICS=Marketing,Negócios,Produtividade,Liderança,Vendas + +OPENROUTER_API_KEY=sua_chave_openrouter +OPENROUTER_MODEL=seu_modelo +``` + +--- + +## Método 1: systemd (Recomendado para Produção) + +### 4.1 Criar o arquivo de serviço + +```bash +sudo nano /etc/systemd/system/thoragentia.service +``` + +Conteúdo: +```ini +[Unit] +Description=ThorAgentIA - Sistema de Insights via Telegram +After=network.target + +[Service] +Type=simple +User=marco +Group=seu_usuario +WorkingDirectory=/opt/thoragentia/app +ExecStart=/opt/thoragentia/app/venv/bin/python3 /opt/thoragentia/app/main.py +Restart=always +RestartSec=10 +StandardOutput=journal +StandardError=journal +SyslogIdentifier=thoragentia + +# Segurança (opcional mas recomendado) +NoNewPrivileges=true +PrivateTmp=true + +[Install] +WantedBy=multi-user.target +``` + +> **Importante**: Substitua `seu_usuario` pelo usuário real do sistema (não use root). + +### 4.2 Habilitar e iniciar o serviço + +```bash +# Recarregar configurações do systemd +sudo systemctl daemon-reload + +# Habilitar inicialização automática no boot +sudo systemctl enable thoragentia.service + +# Iniciar o serviço +sudo systemctl start thoragentia.service +``` + +### 4.3 Comandos de gerenciamento + +```bash +# Verificar status do serviço +sudo systemctl status thoragentia.service + +# Parar o serviço +sudo systemctl stop thoragentia.service + +# Reiniciar o serviço +sudo systemctl restart thoragentia.service + +# Ver logs em tempo real +sudo journalctl -u thoragentia.service -f + +# Ver últimas 100 linhas de log +sudo journalctl -u thoragentia.service -n 100 + +# Desabilitar inicialização automática +sudo systemctl disable thoragentia.service +``` + +### 4.4 Verificar se está rodando + +```bash +ps aux | grep main.py | grep -v grep +``` + +--- + +## Método 2: screen/tmux (Alternativa Simples) + +### Usando screen + +```bash +# Instalar screen (se não tiver) +sudo apt install -y screen + +# Criar uma nova sessão +screen -S thoragentia + +# Dentro da sessão, executar: +cd /opt/thoragentia/app +source venv/bin/activate +python3 main.py + +# Desanexar da sessão: Ctrl+A, depois D + +# Para retomar a sessão: +screen -r thoragentia + +# Para encerrar a sessão: +# Dentro da sessão: Ctrl+C, depois digite "exit" +``` + +### Usando tmux + +```bash +# Instalar tmux +sudo apt install -y tmux + +# Criar nova sessão +tmux new -s thoragentia + +# Executar: +cd /opt/thoragentia/app +source venv/bin/activate +python3 main.py + +# Desanexar: Ctrl+B, depois D + +# Retomar sessão: +tmux attach -t thoragentia + +# Encerrar sessão: +# Dentro da sessão: Ctrl+C, depois digite "exit" +``` + +--- + +## Método 3: nohup (Execução Simples em Background) + +```bash +cd /opt/thoragentia/app +source venv/bin/activate + +# Executar em background com logs +nohup python3 main.py > thoragentia.log 2>&1 & + +# Verificar PID +ps aux | grep main.py | grep -v grep + +# Parar o processo (substitua PID pelo número real) +kill PID + +# Ou matar todos os processos main.py +pkill -f "python3 main.py" +``` + +--- + +## Logs e Monitoramento + +### Logs do systemd +```bash +# Ver logs do serviço +sudo journalctl -u thoragentia.service --since "1 hour ago" + +# Ver apenas erros +sudo journalctl -u thoragentia.service -p err + +# Limpar logs antigos +sudo journalctl --vacuum-time=7d +``` + +### Logs da aplicação (se usar nohup) +```bash +# Ver logs em tempo real +tail -f thoragentia.log + +# Ver últimas 50 linhas +tail -n 50 thoragentia.log +``` + +--- + +## Atualizações do Sistema + +```bash +cd /opt/thoragentia/app + +# Parar o serviço (se usar systemd) +sudo systemctl stop thoragentia.service + +# Atualizar código (se usar git) +git pull origin main + +# Reinstalar dependências (se necessário) +source venv/bin/activate +pip install -r requirements.txt --upgrade + +# Reiniciar o serviço +sudo systemctl start thoragentia.service +``` + +--- + +## Segurança + +- **Nunca** comite o arquivo `.env` com dados reais +- Use permissões restritivas no `.env`: + ```bash + chmod 600 /opt/thoragentia/app/.env + ``` +- Configure firewall para restringir acesso SSH +- Mantenha o sistema atualizado: `sudo apt update && sudo apt upgrade -y` +- Use chaves SSH para acesso ao VPS (desative senha) + +--- + +## Solução de Problemas + +### Serviço não inicia +```bash +# Verificar logs +sudo journalctl -u thoragentia.service -n 50 + +# Testar execução manual +cd /opt/thoragentia/app +source venv/bin/activate +python3 main.py +``` + +### Erro de permissão +```bash +# Ajustar permissões do diretório +sudo chown -R seu_usuario:seu_usuario /opt/thoragentia +chmod +x /opt/thoragentia/app/iniciar.sh +chmod 600 /opt/thoragentia/app/.env +``` + +### Variáveis de ambiente não carregam +```bash +# Verificar se o .env está no diretório correto +ls -la /opt/thoragentia/app/.env + +# Testar leitura do .env +cd /opt/thoragentia/app +python3 -c "from dotenv import load_dotenv; import os; load_dotenv(); print(os.getenv('TELEGRAM_BOT_TOKEN'))" +``` + +--- + +## Backup + +```bash +# Fazer backup do .env +cp /opt/thoragentia/app/.env /home/seu_usuario/backup-thoragentia-$(date +%Y%m%d).env + +# Backup completo do projeto +tar -czf thoragentia-backup-$(date +%Y%m%d).tar.gz /opt/thoragentia/ +``` + +--- + +## Comandos Rápidos de Referência + +| Ação | Comando (systemd) | Comando (screen/tmux) | Comando (nohup) | +|------|------------------|----------------------|-----------------| +| Iniciar | `sudo systemctl start thoragentia` | `screen -r thoragentia` + `python3 main.py` | `nohup python3 main.py &` | +| Parar | `sudo systemctl stop thoragentia` | `Ctrl+C` dentro da sessão | `pkill -f main.py` | +| Status | `sudo systemctl status thoragentia` | `screen -ls` / `tmux ls` | `ps aux \| grep main.py` | +| Logs | `sudo journalctl -u thoragentia -f` | Ver tela da sessão | `tail -f thoragentia.log` | +| Reiniciar | `sudo systemctl restart thoragentia` | Parar e iniciar novamente | `pkill -f main.py` + `nohup ...` | + +--- + +## Contato + +Para suporte: marcocosta@gmx.com