Initial commit: homelab infrastructure wiki
- Full Obsidian vault content - Host configs (ice, grizzley, ubuntu, proxmox, truenas, panda, hyte) - Media stack documentation - Traefik HA setup - Automation scripts - Bachelor party planning
This commit is contained in:
Hermes Agent
362
homelab/architecture.md
Normal file
362
homelab/architecture.md
Normal file
@@ -0,0 +1,362 @@
|
||||
---
|
||||
project:
|
||||
name: Homelab Architecture
|
||||
status: active
|
||||
category: infrastructure
|
||||
source: live-verification
|
||||
created: 2026-01-06
|
||||
updated: 2026-04-19
|
||||
description: Verified live infrastructure architecture — hosts, networks, services, storage, and routing
|
||||
tags: [infrastructure, homelab, architecture, documentation]
|
||||
---
|
||||
|
||||
# Homelab Infrastructure Architecture
|
||||
|
||||
**Verified**: 2026-04-19 via live SSH and API inspection
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph Internet
|
||||
CF[Cloudflare DNS]
|
||||
end
|
||||
|
||||
subgraph PVE["Proxmox VE — 192.168.50.11 (125GB RAM)"]
|
||||
subgraph Ubuntu["ubuntu VM — 192.168.50.61 (32GB RAM, GTX 1080)"]
|
||||
UT[Traefik v3.6.7 — Primary Ingress]
|
||||
UMon[Prometheus + Grafana + Loki]
|
||||
UMedia[Media Stack — 25 containers]
|
||||
UAuth[Authentik SSO]
|
||||
UAI[AI/Dev — Ollama, Gitea, Qdrant]
|
||||
UImg[Immich Photos]
|
||||
end
|
||||
subgraph TrueNAS["TrueNAS VM — 192.168.50.12 (22GB RAM)"]
|
||||
ZFS1["TrueNAS Pool — 25.4TB (65% used)"]
|
||||
ZFS2["RPiPool — 10.9TB (5% used)"]
|
||||
end
|
||||
LXCT["LXC 102 — traefik (running)"]
|
||||
end
|
||||
|
||||
subgraph Grizzley["grizzley — 192.168.50.84 (RPi 5)"]
|
||||
GT[Traefik v3.6.7 — Edge ACME]
|
||||
Komodo[Komodo — Stack Management]
|
||||
Hermes[Hermes Agent — Telegram Alerts]
|
||||
MC[Minecraft Bedrock]
|
||||
end
|
||||
|
||||
subgraph Ice["ice — 192.168.50.197 (RPi 4)"]
|
||||
OC2[OpenCode — port 4096]
|
||||
CF2[camofox container]
|
||||
end
|
||||
|
||||
subgraph Panda["panda — 192.168.30.196 / 192.168.50.196 (RPi)"]
|
||||
HA[Home Assistant OS]
|
||||
end
|
||||
|
||||
CF -->|*.tophermayor.com| UT
|
||||
CF -->|*.tophermayor.com| GT
|
||||
GT -->|Wildcard Certs via NFS| ZFS1
|
||||
UT -->|NFS Media| ZFS1
|
||||
GT -->|Proxy| UT
|
||||
Komodo -->|files_on_host| Ubuntu
|
||||
Komodo -->|files_on_host| Grizzley
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Host Topology
|
||||
|
||||
| Host | IP | OS | Hardware | Role | Key Services |
|
||||
|------|-----|----|----------|------|-------------|
|
||||
| **ubuntu** | 192.168.50.61 | Ubuntu 24.04.4 LTS | VM (Proxmox, 32GB RAM), NVIDIA GTX 1080 8GB | Primary Docker Host | 59 containers — Traefik, Media Stack, Immich, Authentik, Monitoring, AI/Dev |
|
||||
| **grizzley** | 192.168.50.84 | Ubuntu 25.10 | Raspberry Pi 5 | Edge Ingress | 10 containers — Traefik (ACME), Komodo, Hermes, Minecraft |
|
||||
| **ice** | 192.168.50.197 | Ubuntu 25.10 | Raspberry Pi 4 | Control Plane | OpenCode (systemd), camofox |
|
||||
| **pve** | 192.168.50.11 | Debian (Proxmox 9.1.4) | Bare metal, 125GB RAM (70GB used) | Hypervisor | VMs + LXC containers |
|
||||
| **truenas** | 192.168.50.12 | TrueNAS SCALE 25.10.2.1 | VM on PVE (22GB RAM) | Storage | ZFS pools, NFS exports |
|
||||
| **panda** | 192.168.30.196 / 192.168.50.196 | HA OS (Alpine 3.23.3) | Raspberry Pi | Home Assistant | Smart home hub, Zigbee/Z-Wave |
|
||||
|
||||
### Proxmox VMs and LXC
|
||||
|
||||
| VMID | Name | Status | RAM |
|
||||
|------|------|--------|-----|
|
||||
| 9001 | TrueNAS | Running | 22GB |
|
||||
| 9003 | ubuntu-server | Running | 32GB |
|
||||
| 9100 | W10-migrated | Stopped | — |
|
||||
| LXC 102 | traefik | Running | — |
|
||||
|
||||
---
|
||||
|
||||
## Network Topology
|
||||
|
||||
### VLAN Segments
|
||||
|
||||
| VLAN | Subnet | Purpose | Hosts |
|
||||
|------|--------|---------|-------|
|
||||
| **Main/Prod** | 192.168.1.x | PVE, workstations | Hyte |
|
||||
| **Lab** | 192.168.50.x | Core infrastructure | ubuntu, grizzley, ice, truenas, pve, panda SSH |
|
||||
| **IoT/Home** | 192.168.30.x | Home automation | panda/HA, Matter devices |
|
||||
|
||||
### DNS Zones
|
||||
|
||||
| Zone | Scope | Resolution |
|
||||
|------|-------|------------|
|
||||
| `*.tophermayor.com` | Public | Cloudflare → Traefik ingress |
|
||||
| `*.local.tophermayor.com` | Internal | Traefik routers, local services |
|
||||
| `*.pi.tophermayor.com` | Legacy | grizzley/ice services |
|
||||
|
||||
### Traefik Ingress
|
||||
|
||||
| Instance | Host | Role | SSL |
|
||||
|----------|------|------|-----|
|
||||
| Ubuntu Traefik | 192.168.50.61 | Primary router — handles ~90% of traffic | Cloudflare DNS challenge, certs synced from grizzley |
|
||||
| Grizzley Traefik | 192.168.50.84 | Edge ACME — primary certificate source | Cloudflare DNS challenge, certs on NFS |
|
||||
|
||||
Entry points: `web` (80 → HTTPS redirect), `websecure` (443), `metrics` (8080)
|
||||
|
||||
---
|
||||
|
||||
## Service Inventory
|
||||
|
||||
### Media Stack (ubuntu — 25 containers)
|
||||
|
||||
| Service | URL | Description |
|
||||
|---------|-----|-------------|
|
||||
| **Jellyfin** | `jellyfin.tophermayor.com` | Media streaming (GPU transcoding) |
|
||||
| **Jellyseerr** | `jellyseerr.tophermayor.com` | Request management |
|
||||
| **Sonarr** | `sonarr.local.tophermayor.com` | TV automation |
|
||||
| **Sonarr Anime** | — | Anime TV automation |
|
||||
| **Radarr** | `radarr.local.tophermayor.com` | Movie automation |
|
||||
| **Radarr Anime** | — | Anime movie automation |
|
||||
| **Lidarr** | `lidarr.local.tophermayor.com` | Music automation |
|
||||
| **Prowlarr** | `prowlarr.local.tophermayor.com` | Indexer management |
|
||||
| **Bazarr** | — | Subtitle management |
|
||||
| **qBittorrent** | — | Torrent client (via Gluetun VPN) |
|
||||
| **SABnzbd** | `sabnzbd.local.tophermayor.com` | Usenet downloader |
|
||||
| **Gluetun** | — | WireGuard VPN (NordVPN) — all media traffic routes here |
|
||||
| **Flaresolverr** | — | CAPTCHA solver |
|
||||
| **Recyclarr** | — | Quality profile sync |
|
||||
| **Analyzarr** | — | Media analysis |
|
||||
| **Stremio Server** | `stremio.local.tophermayor.com` | Stremio streaming |
|
||||
| **Tdarr** | `tdarr.local.tophermayor.com` | Media transcoding (GPU) |
|
||||
| **Navidrome** | — | Music streaming |
|
||||
| **Calibre** | — | eBook management |
|
||||
| **Calibre-Web** | — | eBook reader |
|
||||
| **Kavita** | — | Manga/comic reader |
|
||||
| **Audiobookshelf** | — | Audiobook/podcast server |
|
||||
| **LazyLibrarian** | — | Book automation |
|
||||
| **Musicseerr** | — | Music request system |
|
||||
| **Nzbdav** | — | Usenet helper |
|
||||
|
||||
### Media Applications (ubuntu — 4 containers)
|
||||
|
||||
| Service | Description |
|
||||
|---------|-------------|
|
||||
| **RecCollection** (backend + postgres) | Media recommendation engine |
|
||||
| **Unified Media Manager** (backend + frontend) | Unified media management |
|
||||
|
||||
### Immich (ubuntu — 4 containers)
|
||||
|
||||
| Service | URL | Description |
|
||||
|---------|-----|-------------|
|
||||
| **Immich Server** | `immich.tophermayor.com` | Photo/video management |
|
||||
| **Immich ML** | — | Machine learning (GPU) |
|
||||
| **Immich Postgres** | — | Dedicated PostgreSQL (pgvecto-rs) |
|
||||
| **Immich Redis** | — | Caching |
|
||||
|
||||
### Auth and SSO (ubuntu — 3 containers)
|
||||
|
||||
| Service | URL | Description |
|
||||
|---------|-----|-------------|
|
||||
| **Authentik Server** | `auth.tophermayor.com` | SSO identity provider (2025.2) |
|
||||
| **Authentik Worker** | — | Background tasks |
|
||||
| **Authentik Redis** | — | Session caching |
|
||||
|
||||
### Monitoring (ubuntu — 8 containers)
|
||||
|
||||
| Service | URL | Description |
|
||||
|---------|-----|-------------|
|
||||
| **Prometheus** | `prometheus.local.tophermayor.com` | Metrics collection |
|
||||
| **Grafana** | `grafana.local.tophermayor.com` | Dashboards |
|
||||
| **Loki** | — | Log aggregation |
|
||||
| **Promtail** | — | Log shipping |
|
||||
| **Alertmanager** | — | Alert routing → Hermes webhook → Telegram |
|
||||
| **Blackbox Exporter** | — | HTTPS probes |
|
||||
| **Node Exporter** | — | Host metrics |
|
||||
| **cAdvisor** | — | Container metrics |
|
||||
|
||||
Scrape targets: ubuntu (local), proxmox, truenas, grizzley, ice, panda
|
||||
|
||||
### AI and Dev (ubuntu — 4 containers)
|
||||
|
||||
| Service | URL | Description |
|
||||
|---------|-----|-------------|
|
||||
| **Ollama** | — | Local LLM inference (GPU) |
|
||||
| **Gitea** | `gitea.tophermayor.com` | Git server (SSH: 2222) |
|
||||
| **Faster Whisper Server** | — | Speech-to-text |
|
||||
| **Docker OSX** | — | macOS VM |
|
||||
|
||||
### AI Applications (ubuntu — 7 containers)
|
||||
|
||||
| Service | Description |
|
||||
|---------|-------------|
|
||||
| **AI Job Pipeline** (backend + frontend) | AI task orchestration |
|
||||
| **AI Alert Aggregator** (backend + frontend + postgres) | Alert intelligence |
|
||||
| **AI Media Intelligence** (backend) | Media analysis |
|
||||
| **AI Subscriptions** | Subscription management |
|
||||
| **Homelab Inventory** (backend) | Infrastructure inventory |
|
||||
|
||||
### Infrastructure (ubuntu — 3 containers)
|
||||
|
||||
| Service | Description |
|
||||
|---------|-------------|
|
||||
| **Traefik** | Primary reverse proxy (v3.6.7) |
|
||||
| **Qdrant** | Vector database (port 6333) |
|
||||
| **Registry** | Docker registry |
|
||||
|
||||
### Grizzley Services (10 containers)
|
||||
|
||||
| Service | URL | Description |
|
||||
|---------|-----|-------------|
|
||||
| **Traefik Pi** | `traefik-grizzley.local.tophermayor.com` | Edge ingress + ACME |
|
||||
| **Homepage** | — | Dashboard |
|
||||
| **Komodo** | `komodo.local.tophermayor.com` | Docker stack management (all hosts) |
|
||||
| **Komodo Mongo** | — | Komodo database |
|
||||
| **Hermes Agent** | — | Telegram bot, monitoring, cron jobs |
|
||||
| **Vaultwarden** | `vaultwarden.tophermayor.com` | Password manager (migrated from ubuntu) |
|
||||
| **Uptime Kuma** | — | Uptime monitoring (migrated from ubuntu) |
|
||||
| **AIOMAanager** + DB | — | AI orchestration |
|
||||
| **Minecraft Bedrock** (x2) | — | UDP/19132, UDP/19134 |
|
||||
|
||||
### Ice Services
|
||||
|
||||
| Service | Type | Port | Status |
|
||||
|---------|------|------|--------|
|
||||
| **OpenCode** | systemd | 4096 | Active/enabled |
|
||||
| **camofox** | Docker container | — | Running |
|
||||
|
||||
### OpenCode Cluster
|
||||
|
||||
| Instance | Host | Port | Status |
|
||||
|----------|------|------|--------|
|
||||
| ubuntu | 192.168.50.61 | 4096 | Active |
|
||||
| ice | 192.168.50.197 | 4096 | Active |
|
||||
| grizzley | 192.168.50.84 | 4096 | Inactive/disabled |
|
||||
|
||||
---
|
||||
|
||||
## Database Architecture
|
||||
|
||||
### Consolidated PostgreSQL (`postgres-shared` on ubuntu)
|
||||
|
||||
| Database | Application |
|
||||
|----------|-------------|
|
||||
| `authentik` | Authentik SSO |
|
||||
| `gitea` | Gitea git server |
|
||||
| `vaultwarden` | Vaultwarden password manager |
|
||||
| `sonarr_main` / `sonarr_log` | Sonarr |
|
||||
| `radarr_main` / `radarr_log` | Radarr |
|
||||
| `lidarr_main` / `lidarr_log` | Lidarr |
|
||||
| `prowlarr_main` / `prowlarr_log` | Prowlarr |
|
||||
| `readarr_main` / `readarr_log` | Readarr |
|
||||
|
||||
### Standalone Databases
|
||||
|
||||
| Database | Application | Reason |
|
||||
|----------|-------------|--------|
|
||||
| `immich_postgres` | Immich | Requires pgvecto-rs extension |
|
||||
| `komodo-mongo` | Komodo | MongoDB |
|
||||
| `aiomanager_db` | AIOMAanager | MongoDB |
|
||||
|
||||
### Redis Instances
|
||||
|
||||
- `authentik-redis` → Authentik caching/session
|
||||
- `immich_redis` → Immich caching
|
||||
|
||||
### Vector Database
|
||||
|
||||
- **Qdrant** (`ubuntu:6333`) — shared memory backend for OpenCode cluster
|
||||
|
||||
---
|
||||
|
||||
## Storage Architecture
|
||||
|
||||
### ZFS Pools (TrueNAS)
|
||||
|
||||
| Pool | Size | Used | Datasets |
|
||||
|------|------|------|----------|
|
||||
| **TrueNAS** | 25.4TB | 65% | Media, backups, shares |
|
||||
| **RPiPool** | 10.9TB | 5% | Reserve storage |
|
||||
|
||||
### NFS Exports
|
||||
|
||||
| Export | Mount on Consumer | Used By |
|
||||
|--------|-------------------|---------|
|
||||
| `/mnt/truenas/mediadata` | `/mnt/truenas/mediadata` on ubuntu | Jellyfin, *Arrs, Immich uploads |
|
||||
| `/mnt/PersonalMediaLibrary` | `/mnt/PersonalMediaLibrary` on ubuntu | Immich external library |
|
||||
| `/mnt/truenas/traefik-certs/grizzley` | NFS on grizzley | Traefik TLS certificates |
|
||||
|
||||
### Local Storage (ubuntu)
|
||||
|
||||
| Path | Purpose |
|
||||
|------|---------|
|
||||
| `/home/bear/homelab/ubuntu/*/data/` | Service data volumes |
|
||||
| `/home/bear/homelab/ubuntu/ollama/data` | Ollama models |
|
||||
| `/home/bear/homelab/ubuntu/tdarr/temp` | Tdarr transcode temp |
|
||||
|
||||
---
|
||||
|
||||
## Monitoring Pipeline
|
||||
|
||||
```
|
||||
Node Exporters (all hosts)
|
||||
→ Prometheus (ubuntu:9090)
|
||||
→ Grafana (ubuntu:3000)
|
||||
→ Alertmanager (ubuntu:9093)
|
||||
→ Hermes Webhook (grizzley:8644)
|
||||
→ Telegram (@tbd1220)
|
||||
```
|
||||
|
||||
### Log Pipeline
|
||||
|
||||
```
|
||||
Docker containers (ubuntu)
|
||||
→ Promtail (Docker socket SD)
|
||||
→ Loki (ubuntu:3100)
|
||||
→ Grafana dashboards
|
||||
```
|
||||
|
||||
### Alerting
|
||||
|
||||
- **Prometheus alert rules** → Alertmanager → Hermes webhook → Telegram
|
||||
- **Hermes cron jobs**: Health Check (15m), Container Monitor (30m), Maintenance (6h)
|
||||
- **Watchdog**: `/home/bear/watchdog/watchdog.sh` monitors SSH/HTTPS/TCP on all hosts
|
||||
|
||||
### Uptime Monitoring
|
||||
|
||||
- **Uptime Kuma** (grizzley) — external/internal availability checks
|
||||
- **Blackbox Exporter** — 15+ HTTPS probe targets
|
||||
|
||||
---
|
||||
|
||||
## SSH Quick Reference
|
||||
|
||||
| Host | Command | User | Key |
|
||||
|------|---------|------|-----|
|
||||
| ubuntu | `ssh bear@192.168.50.61` | bear | `~/.ssh/id_ed25519` |
|
||||
| grizzley | `ssh bear@192.168.50.84` | bear | `~/.ssh/id_ed25519` |
|
||||
| ice | `ssh bear@192.168.50.197` | bear | `~/.ssh/id_ed25519` |
|
||||
| pve | `ssh bear@192.168.50.11` | bear | `~/.ssh/id_ed25519` |
|
||||
| truenas | `ssh truenas` | christopher | `~/.ssh/truenas_pve` via config |
|
||||
| panda | `ssh bear@192.168.50.196` | bear | `~/.ssh/id_ed25519` (SSH add-on) |
|
||||
|
||||
---
|
||||
|
||||
## Related Docs
|
||||
|
||||
- [[project.md|Homelab Project Overview]]
|
||||
- [[dns-traefik.md|DNS and Traefik Configuration]]
|
||||
- [[proxmox-setup.md|Proxmox Setup]]
|
||||
- [[truenas-config.md|TrueNAS Configuration]]
|
||||
- [[network-config.md|Network Configuration]]
|
||||
- [[../automation/scripts.md|Automation Scripts]]
|
||||
Reference in New Issue
Block a user