Manual de Implementação¶
Guia passo a passo para implementar o servidor doméstico. Siga na ordem. Para a primeira subida, o Roteiro do primeiro deploy junta as seções numa sequência só, com o vault gerado pelo scripts/gerar_vault.py.
Estrutura¶
- Preparação e Planejamento: Requisitos e estrutura do projeto.
- Máquina de Controle Ansible: Ambiente de gestão da infraestrutura.
- Proxmox VE Host: Hypervisor, ZFS e NFS.
- Provisionamento de VMs: VMs
core-services-vmeai-desktop-vm. - Configuração Base das VMs: Docker, redes e Portainer.
- Rede Segura: Configuração de Traefik, Cloudflare Tunnel e Authelia.
- Deploy Core: Subida da stack
core(Traefik, Cloudflared e Authelia). - Deploy de Apps: Prometheus, Grafana, Loki, n8n, Home Assistant.
- Stack de IA: gateway LiteLLM (apelidos de modelo, chaves por cliente, uso e Jev), Open WebUI, Ollama com Vulkan e o Claude Code.
- Painel e Notificações: Homepage, alertas do Grafana, Diun e notificações no Telegram via n8n.
- Mídia: Jellyfin, Seerr, Sonarr, Radarr, Lidarr, Prowlarr, Bazarr e qBittorrent atrás da ProtonVPN, com importação por hardlink.
- Fotos e Arquivos: Immich, Nextcloud e Collabora, com login OIDC do Authelia.
- Segundo Cérebro: vaults do Obsidian pelo Syncthing, busca local (qmd) e MCP para o Claude com escopo por vault.
- Agentes: Base: hub de MCPs com leitura pública e controle pela VPN, operações (containers, stacks, Ansible) e rastreio no Langfuse.
- VPN (Tailscale): acesso de fora sem o limite do túnel, rota de controle do hub só pela VPN, DNS da VPN e firewall das portas do Docker.
- IA que observa o servidor: análise de cada alerta e boletim da manhã no Telegram, por uma IA que só lê (rota de leitura do hub).
- Posto de agentes: Claude Code em paralelo pelo Vibe Kanban, e cada ação dos agentes no servidor esperando a sua aprovação no Telegram ou na tela.
- Assistente (Hermes): assistente no Telegram que lê o servidor, busca e escreve nas notas e guarda memória, sem terminal.
- Roteiro do primeiro deploy: a ordem de contas, vault, playbooks e stacks da primeira subida.
A lista completa de aplicações, com stack, exposição e dados de cada uma, está no Catálogo de Aplicações; as integrações entre elas, no Índice de Integrações.
A conferir no primeiro deploy¶
Estes pontos foram desenhados e testados no repositório, mas só dá para confirmar com o servidor rodando. Na primeira subida de cada seção, confira o item correspondente:
| Seção | O que conferir | Como |
|---|---|---|
| 5 | Authelia 4.39 sem erro nem aviso de chave obsoleta (session.cookies, identity_validation, claims_policies) e o Traefik v3.7 sem aviso de opção faltando; o forward-auth novo (/api/authz/forward-auth) manda ao portal quem não entrou e volta à página pedida |
docker logs authelia, docker logs traefik; abrir grafana. numa janela anônima |
| 5 | Um X-Forwarded-Host forjado não pula o Authelia (trustForwardHeader: "false") |
De fora de casa: curl -sI -H 'X-Forwarded-Host: jellyfin.seudominio.com' https://prometheus.seudominio.com/ responde 302 para auth. |
| 5 | Os clientes OIDC recebem e-mail, nome e grupos (política legado de claims no ID token) |
Entrar no Immich, Nextcloud, Open WebUI, Langfuse e num conector MCP |
| 5 | Um usuário fora do grupo admins é recusado nos painéis de administração (authelia_dominios_admins) e não ganha conta no Open WebUI nem no Langfuse |
Crie um usuário de teste só com o grupo users e tente abrir grafana. e llm. |
| 9 | O Diun lê as imagens pelo docker-socket-proxy (se faltar uma permissão do proxy, o log do Diun mostra 403) |
docker logs diun, docker logs diun_ai |
| 9 | O alerta timer-falhou dispara uma vez por falha |
sudo systemctl start backup-litellm-db.service com o banco parado |
| 10 | Widget jellyseerr da Homepage com o Seerr (mesma API); se a Homepage fixada ganhar o widget seerr, troque |
Homepage, grupo Mídia |
| 11 | O editor do Collabora abre dentro do Nextcloud apesar do X-Frame-Options: SAMEORIGIN global (o frame-ancestors do Collabora deve prevalecer) |
Abrir um .docx no Nextcloud; console do navegador |
| 11, 8, 12, 13 | Login OIDC pela LAN (extra_hosts de auth. para o Traefik da core-services-vm) |
Entrar no Immich, no Open WebUI e no Langfuse; docker logs sem erro de TLS ou de descoberta |
| 12 | Módulos nativos do qmd no node:22-bookworm-slim, HOME gravável do markitdown com --user, a "Default Folder" criada pelo generate do Syncthing e o notes_escrita com sistema de arquivos só leitura (read_only) |
docker logs qmd, primeira rodada do notes-documentos, painel do Syncthing, uma nota criada pela escrita |
| 13 | agentgateway em execução: lista de leitura, chaves, tokens em arquivo, statefulMode: stateless, traces no Langfuse e o campo cliente nos logs e no registro do ops |
Teste de ponta a ponta da seção 13; docker logs agentgateway, docker logs ops_controle |
| 15 | O observador chama as ferramentas da rota de leitura (nomes com prefixo, respostas em SSE do hub em modo stateless) e o teste do ponto de contato do Grafana chega analisado; o gasto por análise (campo tokens) cabe no orçamento |
docker exec observador python -m observador boletim; Test da integração observador-webhook; docker logs observador; tela de uso do LiteLLM |
| 16 | Vibe Kanban compilado roda o Claude Code pelo LiteLLM; os perfis DEFAULT (pede aprovação) e AUTONOMO aparecem na tela; o Claude Code lê o /etc/claude-code/managed-mcp.json; os botões do Telegram chegam e o clique decide; o porteiro (Caddy 2.11.7 com cap_add: NET_BIND_SERVICE) sobe, repassa com o segredo do Traefik e dá 403 sem ele; o Vibe Kanban responde em /api/health atrás dele |
Teste de ponta a ponta da seção 16; docker logs posto, docker logs posto_porteiro, docker logs aprovador |
| 17 | Hermes 0.22.5 lê o config.yaml gerado (modelo custom, os três MCPs, disabled_toolsets com o cronjob, platforms.api_server.enabled: false: nenhuma porta escutando) e só responde aos usuários permitidos |
Teste de ponta a ponta da seção 17; docker logs assistente |
| 1 | O vault.yml do scripts/gerar_vault.py é aceito por todos os playbooks e o Authelia aceita o hash pbkdf2-sha512 do admin |
setup-core-networking.yml --check; entrar em auth. com a senha anotada |
| 13 | PUT /api/stacks do Portainer 2.45 (redeploy pelo ops, pela porta HTTP 9000 do --http-enabled) e o alerta ops-acao-falhou com o formato do Loki |
ops_stack_redeploy de uma stack de teste; uma ação recusada |