---
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]]