homelab-docs/docs/ARCHITECTURE.md

HESTIA — Homelab Infrastructure Documentation

Guardiã do homelab. Documentação viva e evolutiva. Última atualização: 2026-04-08 19:50 Responsável: Héstia (Claude Code via MiniMax-M2.7)

---

1. TOPOLOGIA DE REDE

1.1 Segmentos VLAN

VLAN	Nome	Range IP	Gateway	Função
1 (default)	INFRAESTRUTURA	10.0.0.1/24	10.0.0.1	Servidores, Proxmox, TrueNAS
10	GERAL	10.0.10.1/24	10.0.10.1	Computadores, celulares
20	IOT	10.0.20.1/24	10.0.20.1	Dispositivos IoT
30	GUESTS	10.0.30.1/24	10.0.30.1	Visitantes

1.2 Gateway/Router

• Device: TP-Link ER605 (controlado via Omada Controller)
• WAN: Loadbalancer dual ISP (OI + Starlink)
• LAN: 10.0.0.1 (VLAN1), 10.0.10.1 (VLAN10), 10.0.20.1 (VLAN20), 10.0.30.1 (VLAN30)
• DHCP: Estático por MAC no Omada Controller

1.3 DNS/Proxy

• Adguard Home: Roteia *.hackerfortress.cc internamente para serviços com SSL
• Nginx Proxy Manager: Terminção SSL dos serviços internos
• Domínio: hackerfortress.cc

1.4 Acesso Externo

• Twingate: VPN para acessar infraestrutura remotamente (TrueNAS, Proxmox)
• Tailscale: VPN mesh para VPS externas (não usado no homelab)
• NordVPN: Expirou — necessidade de migrar para WireGuard (TODO)

---

2. MÁQUINAS E HARDWARE

2.1 TrueNAS (NAS + Apps)

Atributo	Valor
Hostname	truenas
IP	10.0.0.30
Sistema	TrueNAS SCALE (Debian 12 Bookworm)
Kernel	6.12.15-production+truenas
Uptime	3h 54min
CPU	Intel Xeon E5-2650 v4 @ 2.20GHz (24 cores, 48 threads)
RAM	31 GiB total (5.3 GiB usado, 25 GiB disponível)
SSH	Habilitado (porta 22, usuário root)

Storage Pools:

Pool	Size	Used	Free	Health	Mountpoint
Ikky	2.72T	1.32T (48%)	1.40T	ONLINE	/mnt/Ikky
Hyoga	1.81T	1.09T (60%)	741G	ONLINE	/mnt/mnt/Hyoga
boot-pool	236G	5.91G (2%)	230G	ONLINE	-

Datasets principais:

• Ikky/data — 199G usado (compartilhamento SMB)
• Ikky/.system — configurações do sistema TrueNAS
• Ikky/ix-apps — apps catalog (contém n8n e uptime-kuma datasets)
• Hyoga/media — 923G de mídia (backup final 2025-12-05)
• Hyoga/raidfortress — 192G

Portas abertas:

Porta	Serviço
22	SSH
80/443	Nginx (TrueNAS WebUI + reverse proxy)
445/139	Samba
3260	iSCSI
5357	wsdd (Web Services Discovery)
6000	TrueNAS API (middleware)
6999	netdata

Serviços de App (ix-apps):

• n8n — datasets em /mnt/.ix-apps/app_mounts/n8n/ (múltiplas versões snapshots)
• uptime-kuma — dataset em /mnt/.ix-apps/app_mounts/uptime-kuma/
• ✅ FIXED (2026-04-08): ix-apps datasets agora montam automaticamente com canmount=on

2.2 Proxmox (Hypervisor)

Atributo	Valor
Hostname	pve
IP	10.0.0.20
Sistema	Proxmox VE 8.4.17
Kernel	6.8.12-9-pve
Uptime	3h 54min
CPU	AMD Ryzen 7 2700 Eight-Core (8 cores, 16 threads)
RAM	32 GiB total (26 GiB usado, 5.0 GiB disponível)
Swap	8 GiB
SSH	Habilitado (porta 22, usuário root)
Interface Web	Porta 8006

Disco:

• /dev/sda — 223.6G
  • sda1: 1M (BIOS boot)
  • sda2: 1G (/boot/efi)
  • sda3: 222.6G (LVM)
    • pve-swap: 8G
    • pve-root: 65.6G (/)
    • pve-data: 130.3G (LVM-thin)

Storages:

Storage	Type	Size	Used	Available
local	dir	31.2G	-	64.1G
local-lvm	lvmthin	130.3G	102.8G	26.7G

VMs:

VMID	Nome	Status	vCPUs	RAM	Disk	Uptime
100	homeassistant	running	4	4 GB	32 GB	3h 38min
102	dockerino	running	8	10 GB	74 GB	3h 38min
103	media	running	8	16 GB	64 GB	3h 37min

2.3 Dockerino (VM Proxmox)

Atributo	Valor
Hostname	dockerino
IP	10.0.0.50
Sistema	Debian (5.10.0-23-amd64)
Uptime	3h 54min
CPU	8 vCPUs (Common KVM processor)
RAM	9.7 GiB (4.5 GiB usado, 4.8 GiB disponível)
Disk	31G (/dev/sda1) — 90% usado
Docker	Docker version 28.5.0
Compose	Multi-stack em /root/dockerino/

Docker Stacks em /root/dockerino/:

• nginx/ — Nginx Proxy Manager
• adguard/ — Adguard Home
• bookstack/ — BookStack (com MySQL)
• outline/ — Outline Wiki (PostgreSQL + Redis + MinIO)
• flatnotes/ — FlatNotes
• homer/ — Homer (dashboard)
• homebox/ — HomeBox (inventory)
• omada-controller/ — TP-Link Omada Controller
• picsur/ — Picsur (image hosting)
• speedtest/ — Speedtest Tracker
• twingate/ — Twingate Connector

Containers ativos:

Container	Status	Ports	Imagem
outline	healthy	3001	outlinewiki/outline:latest
outline-minio	healthy	9000-9001	quay.io/minio/minio
outline-postgres	healthy	5432	postgres:15-alpine
outline-redis	healthy	6379	redis:7-alpine
bookstack	healthy	8082→80	solidnerd/bookstack:latest
picsur	healthy	8091→8080	ghcr.io/caramelfur/picsur:latest
homer	healthy	8090→8080	b4bz/homer:latest
twingate	healthy	-	twingate/connector:latest
mysql	healthy	3306	mysql:8.3
speedtest	healthy	8765→80	henrywhitaker3/speedtest-tracker:latest
nginx	healthy	80-81, 443	jc21/nginx-proxy-manager:latest
omada-controller	healthy	network_mode=host	mbentley/omada-controller:latest
homebox	healthy	3100→7745	ghcr.io/hay-kot/homebox:latest
flatnotes	healthy	8089→8080	dullage/flatnotes:latest
postgres	healthy	5432	postgres:14-alpine
adguardhome	healthy	network_mode=host	adguard/adguardhome:latest

⚠️ Alertas:

• twingate unhealthy — healthcheck não configurado corretamente (o Twingate não tem endpoint HTTP para verificar)

2.4 Media (VM Proxmox)

Atributo	Valor
Hostname	media
IP	10.0.0.36
Sistema	Debian (5.10.0-26-amd64)
Uptime	3h 54min
CPU	8 vCPUs (Common KVM processor)
RAM	15 GiB (1.1 GiB usado, 13 GiB disponível)
Disk	62G (/dev/sda2) — 83% usado
Docker	Docker version 28.4.0
Compose	/root/homefortress-media/docker-compose.yml

Docker Stack: Rede customizada mynetwork (172.19.0.0/16)

Container	Status	Ports	Imagem
ollama	removed	11434	ollama/ollama:latest
bazarr	healthy	6767	linuxserver/bazarr:latest
jellyfin	healthy	8096, 8920, 7359/udp	linuxserver/jellyfin:latest
prowlarr	healthy	9696	linuxserver/prowlarr:latest
sonarr	healthy	8989	linuxserver/sonarr:latest
radarr	healthy	7878	linuxserver/radarr:latest
qbittorrent	healthy	5080, 6881	lscr.io/linuxserver/qbittorrent:latest

⚠️ Alertas:

• Nenhum — Ollama foi removido (2026-04-08)

Nota sobre Jellyfin: Tentou usar GPU passthrough (NVIDIA) mas não funcionou. Não há GPU física nesta VM — inference via CPU apenas.

2.5 Home Assistant (VM Proxmox)

Atributo	Valor
VMID	100
Hostname	homeassistant
IP	10.0.0.100
Status	running
Sistema	Linux (EFI boot, machine q35)
vCPUs	4 (x86-64-v2-AES)
RAM	4 GB
Disk	32 GB (local-lvm)
Network	virtio, bridge vmbr0
Boot	EFI, startup order=1
Uptime	3h 38min

Acesso: Via Proxmox (qm guest exec 100)

---

3. MAPEAMENTO DE SERVIÇOS

3.1 Por Máquina

TrueNAS (10.0.0.30):

Serviço	Porta	Status	Notas
SSH	22	✅	Acesso root
TrueNAS WebUI	443	✅	SSL default
Samba	445, 139	✅	Compartilhamento Ikky/data
iSCSI	3260	✅	SCST target
netdata	6999	✅	Monitoramento
n8n	30109	✅	Working (2026-04-08)
Uptime Kuma	31050	✅	Working (2026-04-08)

Dockerino (10.0.0.50):

Serviço	Porta	URL	Status
Nginx Proxy Manager	80, 443	-	✅
Outline Wiki	3001	-	✅
BookStack	8082	bookstack.hackerfortress.cc	✅
Omada Controller	host	-	✅
Adguard Home	host	-	✅
HomeBox	3100	homebox.hackerfortress.cc	✅
FlatNotes	8089	flatnotes.hackerfortress.cc	✅
Homer	8090	-	✅
Picsur	8091	-	✅
Speedtest	8765	-	✅
MySQL	3306	-	✅
PostgreSQL	5432	-	✅
MinIO	9000, 9001	-	✅
Twingate	-	-	✅ healthy

Media (10.0.0.36):

Serviço	Porta	URL	Status
Jellyfin	8096, 8920	media.hackerfortress.cc	✅
Sonarr	8989	-	✅
Radarr	7878	-	✅
Prowlarr	9696	-	✅
Bazarr	6767	-	✅
qBittorrent	5080	-	✅
Ollama	11434	-	⚠️ unhealthy (remover)

Home Assistant (10.0.0.100):

Serviço	Porta	URL	Status
Home Assistant	8123	homeassistant.hackerfortress.cc	✅

3.2 Por Domínio (hackerfortress.cc)

SSL: Let's Encrypt via Nginx Proxy Manager (cert ID 75: *.hackerfortress.cc, expira 2026-05-27)

Subdomínio	Destino NPM	Observação
proxmox.*	10.0.0.20:8006	HTTPS, WebUI Proxmox
proxy.*	nginx:81	NPM Admin Interface
speedtest.*	speedtest:80	Speedtest Tracker
homeassistant.*	10.0.0.100:8123	Home Assistant
qbittorrent.*	10.0.0.36:5080	qBittorrent
prowlarr.*	10.0.0.36:9696	Prowlarr
radarr.*	10.0.0.36:7878	Radarr
sonarr.*	10.0.0.36:8989	Sonarr
jellyfin.*	10.0.0.36:8096	Jellyfin
homebox.*	homebox:7745	HomeBox Inventory
picsur.*	10.0.0.50:8091	Picsur
omada.*	10.0.0.50:8043	HTTPS, Omada Controller
n8n.*	10.0.0.30:30109	n8n Workflow
adguard.*	10.0.0.50:3000	AdGuard Home
flatnotes.*	flatnotes:8080	FlatNotes
truenas.*	10.0.0.30:80	TrueNAS WebUI
uptime.*	10.0.0.30:31050	Uptime Kuma
bookstack.*	bookstack:8080	BookStack Wiki
bazarr.*	10.0.0.36:6767	Bazarr
outline.*	10.0.0.50:3001	Outline Wiki
mcp-outline.*	10.0.0.50:8080	MCP Outline
ollama.*	10.0.0.36:11434	Ollama
openclaw.*	10.0.10.100:18789	OpenClaw
(root)	homer:8080	Homer Dashboard

DNS: AdGuard Home resolve todos *.hackerfortress.cc → 10.0.0.50 (dockerino), exceto openclaw.* → 10.0.10.100. O NPM faz o roteamento interno final.

3.3 Diagrama de Infraestrutura

graph TB
    subgraph INTERNET["🌐 INTERNET"]
        OI["ISP OI"]
        STARLINK["Starlink"]
    end

    subgraph ROUTER["📡 ER605 Omada"]
        GW["Gateway / Load Balance\n10.0.0.1"]
    end

    subgraph HESTIA["hestia · 10.0.10.100"]
        HERMES["🤖 Hermes Agent\n(Telegram)"]
        NPM["🔀 Nginx Proxy Manager\n:81"]
        ADGUARD["🛡️ AdGuard Home\n:3053"]
    end

    subgraph TRUENAS["TrueNAS · 10.0.0.30"]
        N8N["⚙️ n8n\n:30109"]
        KUMA["📊 Uptime Kuma\n:31050"]
        TN_UI["TrueNAS UI\n:443"]
    end

    subgraph DOCKERINO["dockerino · 10.0.0.50"]
        GITEA["📝 Gitea\n:3080/2222"]
        POSTGRES["🗄️ PostgreSQL\n:5432"]
        OUTLINE["📚 Outline Wiki\n:3001"]
        BOOKSTACK["📖 BookStack\n:8082"]
        ADGHOME["🛡️ AdGuard\n(network_mode)"]
        HOMEBOX["📦 HomeBox\n:3100"]
        FLATNOTES["📝 FlatNotes\n:8089"]
        HOMER["🏠 Homer\n:8090"]
        PICSUR["🖼️ Picsur\n:8091"]
        SPEEDTEST["📡 Speedtest\n:8765"]
        OMADA["📶 Omada Controller\n:8043"]
    end

    subgraph MEDIA["media · 10.0.0.36"]
        JELLYFIN["🎬 Jellyfin\n:8096/8920"]
        SONARR["📺 Sonarr\n:8989"]
        RADARR["🎥 Radarr\n:7878"]
        PROWLARR["🔍 Prowlarr\n:9696"]
        BAZARR["📄 Bazarr\n:6767"]
        QBITTORRENT["⬇️ qBittorrent\n:5080"]
    end

    subgraph HA["homeassistant · 10.0.0.100"]
        HOMEASSISTANT["🏠 Home Assistant\n:8123"]
    end

    OI & STARLINK --> GW
    GW --> HESTIA & TRUENAS & DOCKERINO & MEDIA & HA

    %% NPM routing
    NPM -->|SSL Termination| KUMA
    NPM -->|SSL Termination| N8N
    NPM -->|SSL Termination| GITEA
    NPM -->|SSL Termination| JELLYFIN
    NPM -->|SSL Termination| HOMEASSISTANT
    NPM -->|SSL Termination| OUTLINE
    NPM -->|SSL Termination| BOOKSTACK
    NPM -->|SSL Termination| HOMEBOX
    NPM -->|SSL Termination| FLATNOTES
    NPM -->|SSL Termination| PICSUR
    NPM -->|SSL Termination| SPEEDTEST
    NPM -->|SSL Termination| OMADA
    NPM -->|SSL Termination| ADGHOME
    NPM -->|SSL Termination| BAZARR
    NPM -->|SSL Termination| QBITTORRENT
    NPM -->|SSL Termination| SONARR
    NPM -->|SSL Termination| RADARR
    NPM -->|SSL Termination| PROWLARR
    NPM -->|SSL Termination| TN_UI

    %% AdGuard DNS
    ADGUARD -.->|DNS *.hackerfortress.cc| NPM

    %% Internal data flows
    GITEA --> POSTGRES
    OUTLINE --> POSTGRES
    JELLYFIN -.->|media files| QBITTORRENT

    %% Hermes interaction
    HERMES --> NPM

Resumo do fluxo:

1. Usuário acessa servico.hackerfortress.cc
2. AdGuard (10.0.10.100:3053) resolve DNS → 10.0.0.50 (dockerino)
3. Nginx Proxy Manager (dockerino:81) recebe a requisição, termina SSL
4. NPM faz proxy reverso interno para o serviço correto na porta对应
5. Hermes Agent (Telegram) também se comunica via NPM para monitorar status

---

4. ACESSO SSH

4.1 Chave SSH da Héstia

• Created: 2026-04-08
• Type: ED25519
• Fingerprint: SHA256:ieM8FlrvI0ByxVinRa3zfKzP6BYMO2aVGd/IMshTmYU
• Key file: ~/.ssh/id_ed25519
• Public key:

  ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAINEbnDYVvjbDrGuA4SfM8Ex/H/9RVHmkyu7qzCEt27eh hestia-homlelab-20260408
  

4.2 SSH Config ( ~/.ssh/config)

Host truenas
    HostName 10.0.0.30
    User root
    Port 22
    IdentityFile ~/.ssh/id_ed25519

Host proxmox
    HostName 10.0.0.20
    User root
    Port 22
    IdentityFile ~/.ssh/id_ed25519

Host dockerino
    HostName 10.0.0.50
    User root
    Port 22
    IdentityFile ~/.ssh/id_ed25519

Host media
    HostName 10.0.0.36
    User root
    Port 22
    IdentityFile ~/.ssh/id_ed25519

Host homeassistant
    HostName 10.0.0.100
    User root
    Port 22
    IdentityFile ~/.ssh/id_ed25519

4.3 Status Distribuição de Chaves

Máquina	Status
TrueNAS	✅ Distribuída
Proxmox	✅ Distribuída
Dockerino	✅ Distribuída
Media	✅ Distribuída
Home Assistant	❌ Pendente (via Proxmox)

---

5. DOCKER COMPOSE STACKS

5.1 Dockerino Stacks

Localização: /root/dockerino/

Stack	Path	Services
Nginx Proxy Manager	/root/dockerino/nginx/	nginx (jpw/nginx-proxy-manager)
Adguard Home	/root/dockerino/adguard/	adguardhome
BookStack	/root/dockerino/bookstack/	mysql, bookstack
Outline	/root/dockerino/outline/	outline-postgres, outline-redis, outline-minio, outline-minio-init, outline
FlatNotes	/root/dockerino/flatnotes/	flatnotes
Homer	/root/dockerino/homer/	homer
HomeBox	/root/dockerino/homebox/	homebox
Omada Controller	/root/dockerino/omada-controller/	omada-controller
Picsur	/root/dockerino/picsur/	picsur
Speedtest	/root/dockerino/speedtest/	speedtest
Twingate	/root/dockerino/twingate/	twingate

5.2 Media Stack

Localização: /root/homefortress-media/docker-compose.yml

Network: mynetwork (172.19.0.0/16)

Service	IP	Ports
qbittorrent	172.19.0.2	5080, 6881
sonarr	172.19.0.3	8989
prowlarr	172.19.0.4	9696
radarr	172.19.0.5	7878
ollama	172.19.0.10	11434

Volumes:

• /mnt/share-media — dados de mídia (bind mount)

---

6. STORAGE E BACKUPS

6.1 TrueNAS Pools

Ikky (2.72T):

• Ikky/data — 199G usado, compartilhamento SMB principal
• Ikky/.system — configurações TrueNAS
• Ikky/ix-apps — apps catalog (n8n, uptime-kuma)

Hyoga (1.81T):

• Hyoga/media — 923G (backup final 2025-12-05)
• Hyoga/raidfortress — 192G

6.2 Media Mount

/mnt/share-media é o mount point principal para dados de mídia, compartilhado entre Media VM e TrueNAS.

---

7. MONITORAMENTO E ALERTAS

7.1 Alertas Ativos

Severidade	Máquina	Alerta	Ação Recomendada
⚠️ Alta	TrueNAS	n8n/uptime-kuma não sobem após reboot	Investigar bug de pool ix-apps ✅ Resolvido
⚠️ Média	Dockerino	Twingate unhealthy	Configurar healthcheck customizado ou aceitar estado ✅ Resolvido
⚠️ Média	Media	Ollama unhealthy	Remover container e modelos ✅ Resolvido
ℹ️ Info	TrueNAS	ix-apps directory parcialmente populado	Monitorar após fix do bug ✅ Resolvido

7.2 Serviços de Monitoramento

• Uptime Kuma: Ativo no TrueNAS (10.0.0.30:31050) ✅
• netdata: Ativo no TrueNAS (porta 6999)
• Speedtest Tracker: Ativo no Dockerino (porta 8765)

---

8. PROBLEMAS CONHECIDOS E TODOS

8.1 Bugs

• BUG-TRUENAS-01: TrueNAS ix-apps pool não monta automaticamente após reboot ✅ (2026-04-08 - aplicado canmount=on nos datasets)
• BUG-TWINGATE-01: Twingate connector unhealthy — healthcheck não configurado (sem endpoint HTTP) ✅ (2026-04-08 - healthcheck desabilitado)

8.2 Tasks

• TASK-OLLAMA-01: Remover Ollama e modelos baixados do Media ✅ (2026-04-08)
• TASK-VPN-01: Avaliar WireGuard como替代 NordVPN
• TASK-HA-01: Configurar acesso SSH ao Home Assistant via Proxmox guest agent
• TASK-BACKUP-01: Configurar rotina de backup para configurações das VMs
• TASK-DOCS-01: Documentar credenciais de serviços (usar Vault/Pass)

---

9. PRÓXIMOS PASSOS

1. Corrigir bug da pool do TrueNAS (ix-apps) ✅ (2026-04-08)
2. Remover Ollama do Media ✅ (2026-04-08)
3. Configurar Twingate healthcheck ✅ (2026-04-08)
4. Mapear todos os subdomínios e SSL certificates ✅ (2026-04-08)
5. Configurar Uptime Kuma para monitorar todos os serviços ✅ (2026-04-08)
6. Implementar solução de backup (TrueNAS → ?)
7. Avaliar secrets management (Vault/Pass)

---

Documento mantido por Héstia — Guardiã do Homelab Atualizado: 2026-04-08 14:55 UTC-3