📚 homelab docs

Homelab Topology & Service Routing

/p/homelab-topology networkdnsreferencearchitecture

Homelab Topology & Service Routing

Three-tier Traefik architecture — browser → service request flow, all hosts and networks, all routed services. State as of 2026-07-06 (post-grizzley-replacement migration complete).

1. Physical Hosts

Public Edge

Host IP Role
Internet / Public DNS 47.156.104.83 (apex tophermayor.com) Cloudflare authoritative DNS for *.tophermayor.com
UCG Ultra LAN 192.168.1.1, gateway 192.168.50.1 UniFi OS 5.1.x · Network App 10.4.57 · 3 internal VLANs (10, 30, 50) · LAN DNS resolver + DHCP + DNS Policies

Tier 1 — Public Traefik Ingress (LXC)

Host IP Role
CT 102 traefik-lxc 192.168.50.115 (LAN) · public IP via UCG Ultra Debian 13 LXC · traefik:v3.x systemd service · 4 entrypoints: web:80, websecure:443, sshclone:2222, metrics:8080 · ~70 HTTP routers + 1 TCP router

Tier 2 — Forwarder Layer

Host IP Role
VM 9003 ubuntu 192.168.50.61 Ubuntu 26.04 on PVE · own Traefik (public ingress) · file-provider forwarders (priority 250) · 12 non-migrated containers + postgres-shared (kept for 30-day rollback until 2026-08-06)

Tier 3 — New Primary Compute

Host IP Role
Grizzley (NEW) 192.168.50.144 (eth0) · 192.168.10.145 (wlan0, VLAN 10) Raspberry Pi 5 · Ubuntu 26.04 LTS (Resolute Raccoon, arm64) · Docker 29.6.1 + Compose 5.3.0 · bare Traefik 3.0.0 (systemd) · NOPASSWD sudo for bear

Tier 0 — Storage & Other Compute

Host IP Role
TrueNAS 192.168.50.12 NFS server · mediadata, backups, traefik-certs
Ice 192.168.50.197 Pi 4 · Ubuntu 26.04 · Immich + traefik-ice + jump host to PVE
Panda 192.168.30.196 (VLAN 30) Home Assistant OS (smart home control plane)
PVE hypervisor 192.168.50.11 Proxmox VE · runs CT 102, CT 104, CT 200, VM 9003 (ubuntu)
CT 104 (this machine) 192.168.50.x Where the docs webapp is hosted · LXC container on PVE · Hermes default profile
CT 200 media-lxc 192.168.50.200 6c/16GB · GPU-passthrough GTX 1080 · Jellyfin (29.7x HEVC 1080p transcode)

2. Networks & VLANs

Network Range Notes
Production (VLAN 50) 192.168.50.0/24 gateway 192.168.50.1 · 7 clients (truenas, traefik-CT102, termix-CT126, grizzley, hermes-pve-CT104, VectorPro, CT200)
Family / WiFi (VLAN 10) 192.168.10.0/24 grizzley wlan0 .145 lives here
Home Assistant (VLAN 30) 192.168.30.0/24 panda .196
DMZ / Staging (VLAN 40) 192.168.40.0/24
Mgmt / UGC Ultra (VLAN 1) 192.168.1.0/24 UniFi controller at .1
docker bridge (proxy-net) 172.19.0.0/16 grizzley containers & postgres-shared

3. Three-Tier Traefik — Static + Dynamic Config Map

Tier 1 — CT 102 (public Traefik)

/etc/traefik/traefik.yml (STATIC)
  entryPoints:
    web:80         → redirect→websecure
    websecure:443  → websecure routers
    sshclone:2222  → TCP forwarder → gitea
    metrics:8080
/etc/traefik/dynamic/ (file-provider, hot-reload)
  ├── conf.yml                  — wildcard cert + dashboards
  ├── ubuntu.yml                — Host(ubuntu.tophermayor.com) → 192.168.50.61 (legacy)
  ├── gitea-ssh-forwarder.yml   — TCP :2222 → 192.168.50.144:2222
  ├── grizzley-backup-routers.yml
  ├── splash-fallbacks.yml      — priority-1 fallbacks
  ├── media-lxc.yml, pve.yml, truenas.yml, termix.yml, ... — 20+ more
  └── 95 DNS policies via UniFi integration v1

Tier 2 — ubuntu Traefik (FORWARDER ONLY post-migration)

/etc/traefik/dynamic/
  ├── grizzley-auth-forwarder.yml         — Host(auth.tophermayor.com) + PathPrefix(/outpost) → grizzley:9000
  ├── grizzley-migrated-forwarder.yml     — gitea/vaultwarden/navidrome/slskd/homepage → grizzley
  ├── upstream-ingress.yml                — homepage public routes (repointed to .144)
  └── 12+ other files for ubuntu-local services

Tier 3 — grizzley bare Traefik (systemd, NOT docker)

/etc/traefik/traefik.yml (STATIC)
  entryPoints:
    websecure:8443 → app routers
    metrics:8080   (off by default)
/etc/traefik/dynamic/
  ├── authentik.yml — Host(auth.tophermayor.com) → :9000 + PathPrefix(/outpost) → :9000
  └── (each app's compose has its own service exposure via ports:, NOT via traefik labels)
Auth: CF_DNS_API_TOKEN via /etc/traefik/dns-token.env (chmod 600). Cert: Let's Encrypt DNS-01 via Cloudflare (one cert for auth.tophermayor.com).

4. Request Flow — Browser → Service

4a. Generic Public Request (e.g. https://gitea.tophermayor.com)

[Step 1 — DNS resolution (client side)]
Browser/curl → Cloudflare DNS → gitea.tophermayor.com → tophermayor.com apex
            → A 47.156.104.83 (public IP)

[Step 2 — TCP/TLS handshake + HTTP request (Tier 1)]
Browser → UCG Ultra → CT 102 traefik-lxc :443 (websecure entrypoint)
     → TLS SNI=gitea.tophermayor.com → wildcard cert from acme.json
     → dynamic/ubuntu.yml: Host(gitea.tophermayor.com) → ubuntu-traefik svc (priority 100)

[Step 3 — Forwarder (Tier 2)]
ubuntu Traefik :443 → dynamic/grizzley-migrated-forwarder.yml: grizzley-gitea (priority 250)
                → svc gitea-grizzley @ http://192.168.50.144:3000

[Step 4 — Backend (Tier 3)]
grizzley .144:3000 → gitea container (port 3000)
Note: Each service may take additional hops. For auth.tophermayor.com, the backend is :9000 (Authentik). For OIDC forwardAuth on OIDC-protected services, the forwardAuth call hops: CT 102 → ubuntu → grizzley :9000 → outpost.goauthentik.io path.

4b. SSH-clone Request (e.g. git clone gitea.tophermayor.com:2222)

client → Cloudflare → 47.156.104.83:2222
      → CT 102 traefik :2222 (sshclone entrypoint, TCP)
      → dynamic/gitea-ssh-forwarder.yml: tcp.routers.gitea-ssh-public
      → svc gitea-ssh @ 192.168.50.144:2222
      → gitea sshd (port 22 in container)

4c. OIDC ForwardAuth on gitea

browser → CT 102 :443
       → router: Host(gitea.tophermayor.com) middlewares=[forwardAuth,local-only]
       → forwardAuth → http://192.168.50.144:9000/outpost.goauthentik.io/auth/traefik
         (hops ubuntu .61 forwarder)
       → Authentik :9000 checks session, returns 302 to /application/o/authorize/
       → If unauthed: 302 → auth.tophermayor.com/application/o/authorize/?...
       → User logs in via Authentik → cookie set → gitea request succeeds

4d. LAN-only request (e.g. https://gitea.local.tophermayor.com)

LAN client → UCG Ultra LAN DNS (192.168.50.1)
          → A 47.156.104.83 (or direct to 192.168.50.115 if UniFi has split-horizon)
          → CT 102 :443
          → router: Host(gitea.local.tophermayor.com) middlewares=[local-only,forwardAuth]
          → Same as 4a from Tier 2 onward

5. Per-Service Routing Table

Hostname Tier 1 (CT 102) Tier 2 (ubuntu forwarder) Tier 3 (grizzley) Backend Auth
gitea.tophermayor.com ubuntu.yml: gitea-public (100) grizzley-migrated-forwarder: grizzley-gitea (250) — (direct port) 192.168.50.144:3000 (gitea) forwardAuth → auth.tophermayor.com
gitea.tophermayor.com:2222 TCP: gitea-ssh-public (200) — (passthrough) — (direct port) 192.168.50.144:2222 (gitea sshd) SSH key (gitea user account)
vaultwarden.tophermayor.com ubuntu.yml: vaultwarden-public (200) grizzley-migrated-forwarder: grizzley-vaultwarden (250) — (direct port) 192.168.50.144:80 (vaultwarden) forwardAuth (cookie session)
navidrome.tophermayor.com ubuntu.yml: navidrome-public (200) grizzley-migrated-forwarder: grizzley-navidrome (250) — (direct port) 192.168.50.144:4533 (navidrome) navidrome native session
slskd.local.tophermayor.com ubuntu.yml: sldk-local (200) grizzley-migrated-forwarder: grizzley-slskd (250) — (direct port) 192.168.50.144:5030 (slskd) slskd native session
homepage.tophermayor.com upstream-ingress.yml: homepage (100) — (bypassed, Tier 2→Tier 3 direct) — (direct port) 192.168.50.144:3003 (homepage) forwardAuth
homepage.local.tophermayor.com upstream-ingress.yml: homepage-local (100) — (direct) — (direct port) 192.168.50.144:3003 local-only + forwardAuth
homepage-grizzley.local.tophermayor.com upstream-ingress.yml: homepage-grizzley (250) grizzley-migrated-forwarder: grizzley-homepage-grizzley (250) — (direct port) 192.168.50.144:3003 forwardAuth
auth.tophermayor.com — (CT 102 passes through) grizzley-auth-forwarder: grizzley-authentik (100/2001) — (direct port) 192.168.50.144:9000 (authentik) Authentik native login
auth.tophermayor.com/outpost.goauthentik.io/* — grizzley-auth-forwarder: outpost router (2001) — (direct port) 192.168.50.144:9000 — (OIDC forwardAuth endpoint)
immich.tophermayor.com — immich route on ubuntu — (still on ubuntu) 192.168.50.61:2283 (immich) forwardAuth (immich OIDC)
jellyfin.tophermayor.com ubuntu.yml: jellyfin-public (200) — (still on ubuntu) — 192.168.50.200:8096 (jellyfin, media-lxc) jellyfin native
traefik-lxc.lan — (own host) — — 192.168.50.115:8080 (metrics) basic-auth
media-lxc.lan media-lxc.yml routes — (still on media-lxc, .200) — 192.168.50.200 varies

6. DNS Layer Details

Cloudflare (public)

Authoritative for tophermayor.com. 70 records:
  • 3 A-records at public IP 47.156.104.83: opencode, termix, apex tophermayor.com
  • 10 CNAMEs → apex (auth, cloud, gitea, immich, jellyfin, jellyseerr, jfa, minecraft, n8n, vault)
  • ~57 TXT records (_acme-challenge.* for cert validation, DKIM, etc.)
  • navidrome.tophermayor.com added 2026-07-06 (was missing — caused the public 502)

UniFi DNS Policies (LAN)

Authoritative for {host}.lan zones. 95 policies total.
Record Old → New Notes
grizzley.lan .84 → .144 Stale fixed 2026-07-06
ct102.lan (missing) → .115 Added 2026-07-06
ubuntu.lan, ice.lan, pve.lan, truenas.lan, media-lxc.lan already correct Verified 2026-07-06
*.local.tophermayor.com (14 service hostnames) .84 → .144 aiomanager, aiometadata, aiostreams, komodo, metrics-grizzley, minecraft*, oc-grizz, reccollection, starfield, status, traefik-grizzley, traefik-wildcard

7. Migration State

Phase A (Authentik) and Phase B (postgres-shared + 5 apps) complete on 2026-07-06. New grizzley (.144) is the new primary. Public Traefik ingress unchanged: CT 102 → ubuntu (file-provider forwarders) → grizzley (:8443 LAN-side). 30-day rollback window: ubuntu containers stopped, data preserved on disk, postgres-shared still running until 2026-08-06.
2 stale records intentionally NOT changed: *.pi.tophermayor.com → .84 (wildcard, separate host) and oc-ice.local.tophermayor.com → .84 (OpenCode on ice, not grizzley).