PsAgentIA/DEPLOY.md

Deploy — PsAgentIA no Debian 12

Este documento descreve como colocar o sistema PsAgentIA para rodar de forma contínua em um servidor Debian 12 (Bookworm), com auto-start no boot e logs centralizados.

---

1. Pré-requisitos no servidor

sudo apt update
sudo apt install -y python3 python3-venv python3-pip git curl

Acesse o servidor como usuário comum (ex: marco ou ubuntu). NÃO execute como root a menos que saiba o que está fazendo.

---

2. Clonar o repositório

cd ~
git clone <URL_DO_REPOSITORIO> PsAgentIA
cd PsAgentIA/app

---

3. Configurar o ambiente

chmod +x iniciar.sh
cp .env.example .env
nano .env   # edite com suas chaves

Preencha obrigatoriamente:

• TELEGRAM_BOT_TOKEN
• TELEGRAM_CHAT_ID
• pelo menos uma chave de IA (OPENROUTER_API_KEY, STEPFUN_API_KEY ou QWENCLOUD_API_KEY)

---

4. Testar manualmente antes do deploy

./iniciar.sh

Envie uma mensagem no Telegram para o bot. Se responder, pare o processo com CTRL+C e prossiga.

---

5. Criar usuário de serviço dedicado (recomendado)

sudo useradd -r -s /bin/bash -m -d /home/psagentia psagentia
sudo chown -R marco:marco /home/marco/PsAgentIA

Ajuste permissões:

sudo chmod 600 .env

---

6. Criar serviço systemd

Opção A — Serviço de sistema (requer sudo)

Crie o arquivo /etc/systemd/system/psagentia.service:

[Unit]
Description=PsAgentIA - Personal Agent IA Conversacional
After=network.target

[Service]
Type=simple
User=marco
WorkingDirectory=/home/marco/PsAgentIA/app
Environment="PATH=/home/marco/PsAgentIA/app/venv/bin:/usr/local/bin:/usr/bin:/bin"
ExecStart=/home/marco/PsAgentIA/app/venv/bin/python3 /home/marco/PsAgentIA/app/psagentia_agent.py
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Ajuste User e WorkingDirectory conforme seu cenário.

Opção B — Serviço de usuário (não requer sudo)

Se o arquivo psagentia.service já existe em ~/.config/systemd/user/, basta:

systemctl --user daemon-reload
systemctl --user enable --now psagentia.service

---

7. Ativar e iniciar o serviço

Opção A — Serviço de sistema (requer sudo, sobrevive a reboot)

sudo systemctl daemon-reload
sudo systemctl enable psagentia.service
sudo systemctl start psagentia.service

Opção B — Serviço de usuário (sem sudo, NÃO sobrevive a reboot — use se não tiver sudo)

systemctl --user daemon-reload
systemctl --user enable --now psagentia.service

Importante: Se usar a Opção B (serviço de usuário), o processo será morto quando você fizer logout. Para torná-lo persistente mesmo sem login, adicione lingering para o usuário:

sudo loginctl enable-linger marco

Comandos úteis (Opção A — sistema):

sudo systemctl status psagentia.service        # status
sudo journalctl -u psagentia.service -f        # logs em tempo real
sudo systemctl restart psagentia.service       # reiniciar após alterações
sudo systemctl stop psagentia.service          # parar

Comandos úteis (Opção B — usuário):

systemctl --user status psagentia.service              # status
journalctl --user -u psagentia.service -f              # logs em tempo real
systemctl --user restart psagentia.service             # reiniciar
systemctl --user stop psagentia.service                # parar

---

8. Verificar se está funcionando

sudo systemctl status psagentia.service

Envie uma mensagem no Telegram para o bot. Se não houver resposta, verifique os logs:

sudo journalctl -u psagentia.service -n 100 --no-pager

Possíveis causas se não responder

1. Você está mandando mensagem para o bot errado — confira o username do bot (ex: @hermesjogo1000_bot).
2. Chat ID errado — use /debug no bot para ver o chat ID da mensagem e compare com TELEGRAM_CHAT_ID no .env.
3. Token inválido — o bot pode ter sido revogado no @BotFather.
4. Firewall bloqueando saída — teste: curl -s https://api.telegram.org deve funcionar.
5. Chave de IA ausente ou inválida — o bot recebe a mensagem mas não consegue responder; verifique os logs.

---

9. Atualizações

cd /home/marco/PsAgentIA
git pull
cd app
source venv/bin/activate
pip install -r requirements.txt -q
sudo systemctl restart psagentia.service

---

10. Segurança

• Nunca comite o arquivo .env em repositórios públicos.
• Restrinja permissões: chmod 600 .env.
• Revogue tokens expostos e gere novos no @BotFather ou nos provedores de IA.
• Considere usar um .env fora do diretório do projeto se o servidor for compartilhado.

---

11. Estrutura final no servidor

/home/marco/PsAgentIA/
├── app/
│   ├── psagentia_agent.py
│   ├── iniciar.sh
│   ├── .env
│   ├── requirements.txt
│   ├── user_profile.json
│   ├── contexts/
│   │   └── YYYY-MM-DD.json
│   ├── README.md
│   └── LICENSE
├── venv/          # ambiente virtual local
└── .git/

Serviço: /etc/systemd/system/psagentia.service