2.2 Docker + auto-deploy

📦 Por que rodar Docker

Você poderia instalar o Hermes direto no Ubuntu com pip install hermes-agent. Vai funcionar. Mas vai virar pesadelo assim que você quiser rodar 2 perfis em paralelo, atualizar o Python ou desinstalar limpo. Docker resolve isso de uma vez.

🎁O que Docker entrega ao Hermes

Isolamento: filesystem próprio, dependências próprias, .env próprio. Não polui o host.
Multi-agente: rodar pessoal + marketing + financeiro lado a lado, cada um com chaves diferentes.
Atualização atômica: docker compose pull && up -d troca a imagem inteira sem mexer em nada do host.
Reprodutibilidade: mesmo docker-compose.yml sobe agente idêntico em qualquer VPS.
Rollback: deu errado? Volta pra imagem anterior em 30 segundos.

🧠Mental model

Imagem = template congelado, vem do Docker Hub. Container = imagem em execução, descartável. Volume = pasta persistente fora do container — é onde memória, skills e SQLite vivem. Atualizar a imagem destrói o container, mas o volume permanece. Se você botou tudo no volume, a atualização é zero-loss.

⬇️ Instalar Docker no Ubuntu

A forma certa em 2026: script oficial da Docker ou app one-click do Hostinger. Evite apt install docker.io — pacote do Ubuntu costuma estar 6+ meses atrasado e quase nunca traz o compose plugin v2.

📜 Instalação via script oficial

# Conectado como hermes (com sudo)
curl -fsSL https://get.docker.com | sudo sh

# Adicionar usuário ao grupo docker (rodar sem sudo)
sudo usermod -aG docker $USER

# Logout e login pra ativar grupo (ou: newgrp docker)
exit
ssh hermes@SEU_IP

# Verificar instalação
docker --version
docker compose version  # nota: SEM hífen
docker run hello-world

⚠️Pegadinha do compose v1 vs v2

✗v1 (descontinuado): docker-compose (com hífen), Python.
✓v2 (atual): docker compose (sem hífen), Go, plugin do Docker Engine.
Tutoriais antigos usam v1 e quebram silenciosamente. Sempre use o v2.

💡Atalho Hostinger

No painel da Hostinger, em VPS → Marketplace, "Docker" é one-click. Sobe Ubuntu 24.04 + Docker Engine + Compose v2 já configurados. Pula os passos manuais. Útil pra primeira vez.

📜 docker-compose.yml para Hermes

Esse é o arquivo que orquestra tudo. Volume bind mount garante persistência. env_file isola secrets. restart policy traz o agente de volta após reboot. TZ evita pegadinha de horário.

📄 docker-compose.yml mínimo

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    tty: true
    stdin_open: true
    env_file: .env
    environment:
      - TZ=America/Sao_Paulo
    volumes:
      - ~/.hermes:/root/.hermes
    networks:
      - hermes-net

networks:
  hermes-net:
    driver: bridge

🔍 Decifrando linha por linha

image: qual versão do Hermes baixar. :latest pega sempre a mais nova.
restart: unless-stopped: sobe sozinho após reboot, mas não reinicia se você parou manualmente.
tty + stdin_open: habilita docker exec -it hermes hermes com TUI completa.
env_file: .env: lê variáveis do .env do host pra dentro do container.
volumes ~/.hermes:/root/.hermes: pasta do host vira pasta do container — persistência.
TZ=America/Sao_Paulo: ajusta timezone do container (default é UTC).

⚠️Erros comuns nesse arquivo

Esquecer o volume: recriou o container? Memória, skills, SQLite — tudo perdido.
Path relativo no volume: ./hermes:/root/.hermes depende do diretório de execução. Use absoluto ou ~/.
Sem tty: a CLI do Hermes vira um log de strings sem cor nem formatação.
Sem TZ: crons disparam 3 horas antes do esperado (UTC vs Brasília).

🚀 Primeira subida: docker compose up

Tudo pronto no docker-compose.yml. Hora da subida. A primeira vez é onde quase tudo dá errado — token faltando, volume com permissão errada, .env não montado. Saber ler logs e identificar sintoma encurta horas em minutos.

⚡ Sequência de subida

# Na pasta com docker-compose.yml e .env
cd ~/hermes-deploy

# Subir em background (-d = detached)
docker compose up -d

# Acompanhar logs em tempo real (-f = follow)
docker logs -f hermes

# Entrar na CLI interativa do agente
docker exec -it hermes hermes

# Verificar que está rodando
docker ps

✓ Sinais de sucesso

✓docker ps mostra container hermes com status Up X minutes
✓Logs sem erros vermelhos, mensagem "Agent ready" ou similar
✓docker exec -it hermes hermes abre o prompt interativo
✓~/.hermes/ no host tem arquivos (SOUL.md, state.db) criados pelo container

✗ Sintomas de problema

✗"Permission denied" no volume → ajuste UID/GID ou chown
✗"Missing API key" → .env não está sendo lido (path errado ou nome errado)
✗Container reinicia em loop → ver docker logs hermes --tail 50
✗"image not found" → typo no nome da imagem ou tag inexistente

🔧 Comandos do dia-a-dia

Cinco comandos cobrem 90% das operações com Hermes em Docker. Decorar é o que separa quem volta no Stack Overflow toda vez de quem opera o agente em fluxo.

🛠️ Os 5 comandos essenciais

# 1. Subir / atualizar
docker compose up -d

# 2. Reiniciar (após mudar config ou .env do container)
docker compose restart

# 3. CLI interativa do agente
docker exec -it hermes hermes

# 4. Setar config dentro do container (escreve em /root/.hermes/.env)
docker exec -it hermes hermes config set TELEGRAM_TOKEN xxx

# 5. Ver logs
docker logs hermes --tail 100
docker logs -f hermes  # follow modo

📚 Comandos secundários úteis

docker compose pull — baixa imagem nova sem subir
docker compose down — para tudo (preserva volumes!)
docker compose ps — status de cada serviço
docker compose logs hermes --since 1h — logs da última hora
docker stats hermes — uso de CPU e memória em tempo real
docker exec hermes env | grep TELEGRAM — checar variáveis carregadas

🔥Comandos perigosos — atenção

docker compose down -v — apaga VOLUMES junto. Adeus memória, skills, SQLite. NUNCA em produção.
docker system prune -a — apaga TODAS as imagens não usadas. Cuidado se tiver outros projetos.
docker rm -f hermes — remove o container forçado. Volume sobrevive, mas confunde compose.

🔄 Atualização sem perder dados

Hermes lança versões frequentes (v0.13.0 em 7 de maio de 2026, "The Tenacity Release"). Você precisa atualizar com confiança. O fluxo correto preserva tudo que importa — memória, skills, SQLite, configs — porque está no volume.

🔁 Fluxo de atualização seguro

# 1. Backup do volume (sempre antes de atualizar)
tar czf hermes-backup-$(date +%Y%m%d).tgz ~/.hermes

# 2. Baixar imagem nova
docker compose pull

# 3. Recriar container com nova imagem
docker compose up -d

# 4. Verificar versão
docker exec hermes hermes --version

# 5. Conferir logs por 1-2 minutos
docker logs -f hermes

# Se algo deu errado, voltar para tag específica:
# editar docker-compose.yml: image: nousresearch/hermes-agent:0.12.5
# docker compose up -d

✓Por que esse fluxo é seguro

Tar de backup: 30 segundos, salva sua vida em rollback.
Pull antes de up: imagem baixada com sucesso antes de mexer no container atual.
Volume preservado: ~/.hermes não é tocado quando o container é recriado.
Rollback fácil: trocar tag pra versão anterior + up -d volta tudo.

💡Dica de pinning

Em produção crítica, evite :latest. Use tag explícita (:0.13.0). Você decide quando atualizar e tem rollback determinístico. :latest é cômodo pra exploração, mas pode quebrar inesperadamente quando uma versão major sai com breaking change.

🎯Resumo do módulo

✓

Docker isola o Hermes — filesystem, deps, .env e volume próprios.

✓

Instalar via script oficial (get.docker.com) — traz engine + compose v2 atualizados.

✓

docker-compose.yml com volume, env_file, restart, TZ — receita pronta pra subir e voltar após reboot.

✓

Cinco comandos do dia-a-dia — up, restart, exec, config set, logs.

✓

Pull + up -d atualiza sem perder dados — volumes preservam memória, skills, SQLite.

Próximo módulo:

2.3 - 🤖 Provedor de inferência e modelo

← Módulo Anterior Próximo Módulo →