Hermes + Traefik + OmniRoute + Docs: como montei o ambiente¶

Este post documenta (de ponta a ponta) como ficou o meu ambiente:

Hermes Agent rodando no Telegram, com memória/skills e cron.
Traefik como reverse proxy central para múltiplos projetos.
OmniRoute como gateway OpenAI-compatible (endpoint /v1).
Docs/Blog com MkDocs Material em docs.andersonc.dev.br.

Nota: os exemplos abaixo evitam expor chaves/segredos. Onde aparecerem variáveis, use .env/secrets.

Visão geral (arquitetura)¶

Objetivo: ter um proxy de entrada (Traefik) e cada app isolado em seu próprio docker-compose, todos na mesma rede externa.

Rede Docker externa: proxy
Traefik (infra): expõe 80/443 no host
Apps (projetos): não expõem portas no host; só publicam na rede proxy

Fluxo:

Cliente acessa https://<host>/...
Traefik roteia por Host(...)
Serviço responde dentro da rede Docker (http://servico:porta)

Parte 1 — Hermes Agent (base + cron)¶

Configuração básica¶

O Hermes pode ser configurado via wizard e config:

hermes setup
hermes model
hermes config edit

Arquivos importantes:

~/.hermes/config.yaml (config)
~/.hermes/.env (segredos)
~/.hermes/logs/ (logs)

Cron (boletim diário)¶

Montei um cronjob para boletim diário (tempo/mercados/notícias). Um ponto importante apareceu durante o setup:

Se ~/.hermes/config.yaml estiver corrompido/não-UTF-8, cron pode cair em defaults e falhar com erro do provedor (No models provided).

Checklist rápido de troubleshooting:

Ver logs em ~/.hermes/logs/
Re-salvar config em UTF-8:
hermes config edit
Se necessário, recriar o job ou “pin” do modelo no job.

Parte 2 — Traefik (infra compartilhada)¶

Configuração do Traefik (proxy central)¶

O Traefik faz o roteamento por hostname e encaminha para os serviços dentro da rede Docker compartilhada.

Provider escolhido: File Provider¶

Eu optei por File Provider (configs em YAML) para o Traefik rotear sem depender do Docker provider/labels.

Traefik (compose) monta:

./acme → estado do Let’s Encrypt
./dynamic → regras dinâmicas (routers/services)

E habilita:

--providers.file.watch=true (reload automático)

ACME / Let’s Encrypt (HTTP-01)¶

Para o certificado sair, precisa:

DNS apontando A/CNAME corretamente
Porta 80 acessível externamente (challenge)
Porta 443 acessível externamente (tráfego HTTPS)

Parte 3 — OmniRoute (gateway de modelos)¶

Subi o OmniRoute via Docker e conectei na rede proxy.

O OmniRoute expõe:

Dashboard: http://localhost:20128 (interno, se você publicar)
API: /v1 (OpenAI-compatible)

No meu setup com Traefik, o OmniRoute fica sem porta no host e o Traefik faz o roteamento por subdomínio, por exemplo:

omni.andersonc.dev.br → http://omniroute:20128

Parte 4 — Docs/Blog com MkDocs Material¶

Queria algo leve, fácil de escrever e com busca. A escolha foi:

squidfunk/mkdocs-material
modo serve (recarrega ao salvar)

Estrutura:

mkdocs.yml (menu, plugins)
docs/index.md
docs/blog/index.md
docs/blog/posts/*.md

Roteamento:

docs.andersonc.dev.br → http://pessoal-docs:8000

Criando um post novo¶

1) Criar arquivo em docs/blog/posts/:

nano /srv/projects/pessoal-docs/docs/blog/posts/AAAA-MM-DD-titulo.md

2) Usar frontmatter:

---
date: AAAA-MM-DD
categories:
  - notas
---

# Título

Conteúdo...

Pronto: o site atualiza automaticamente.

Checklist final¶

[ ] DNS para andersonc.dev.br, www, omni, docs
[ ] Portas 80/443 liberadas no firewall
[ ] Traefik em rede proxy externa
[ ] Serviços (OmniRoute, docs, landing) conectados à rede proxy
[ ] Rotas em dynamic/*.yaml com Host(...) correto

Próximos passos¶

Trocar o MkDocs de serve para modo build + Nginx (produção)
Adicionar autenticação/ACL no Traefik para endpoints sensíveis
Documentar o fluxo padrão: “novo projeto” = compose + rota YAML