5.4 KiB
5.4 KiB
📊 Homelab Infrastructure Diagrams
This directory contains visual documentation of the homelab infrastructure, including network topology, service architecture, and storage layouts. All diagrams use Mermaid.js for rendering.
📁 Diagram Index
| Diagram | Description | Format |
|---|---|---|
| Network Topology | Physical and logical network layout across all locations | Mermaid + ASCII |
| Tailscale Mesh | VPN mesh network connecting all locations | Mermaid + ASCII |
| 10GbE Backbone | High-speed network backbone in Concord | Mermaid + ASCII |
| Service Architecture | How services interact, auth flows, CI/CD pipeline | Mermaid |
| Storage Topology | NAS cluster, volumes, and backup flows | Mermaid + ASCII |
| Location Overview | Geographic distribution of infrastructure | Mermaid |
Service Architecture Sections
- Media Stack (Arr suite, Plex, streaming)
- Monitoring Stack (Prometheus, Grafana)
- Authentication Stack (Authentik + NPM) ⭐ NEW
- Communication Stack (Matrix, Mastodon, Mattermost)
- CI/CD Pipeline (Gitea Actions + Ansible) ⭐ NEW
- AI/ML Stack (Ollama, vLLM, Olares)
- DCIM/IPAM (NetBox)
🔐 Key Architecture Components
Authentication & Proxy Stack
┌─────────────────────────────────────────────────────────────────────┐
│ Internet → Cloudflare → NPM (matrix-ubuntu) → Authentik (Calypso) │
│ ↓ │
│ Protected Services │
└─────────────────────────────────────────────────────────────────────┘
| Component | Host | Port | Purpose |
|---|---|---|---|
| Nginx Proxy Manager | matrix-ubuntu | :81/:443 | Reverse proxy, SSL termination |
| Authentik Server | Calypso | :9000 | Identity provider, SSO |
| Authentik Outpost | Calypso | :9444 | Forward auth proxy |
| Headscale | Calypso | :8080 | Self-hosted Tailscale controller |
| WireGuard | Atlantis | :51820 | VPN server |
Service Protection via Authentik
| Domain | Service | Auth Type |
|---|---|---|
| sso.vish.gg | Authentik | - (IdP) |
| git.vish.gg | Gitea | OAuth2/OIDC |
| gf.vish.gg | Grafana | OAuth2/OIDC |
| nb.vish.gg | NetBox | OAuth2/OIDC |
| dash.vish.gg | Homarr | OAuth2/OIDC |
| rx.vish.gg | Reactive Resume | OAuth2/OIDC |
| immich | Immich | OAuth2/OIDC |
| headscale.vish.gg/admin | Headplane | OAuth2/OIDC |
| docs.vish.gg | Paperless-NGX | Forward Auth |
| actual.vish.gg | Actual Budget | Forward Auth |
🗺️ Quick Reference
Locations
- Concord, CA (Primary) - Main infrastructure, 25Gbps fiber
- Concord, CA (Backup ISP) - Failover connectivity, 2Gbps/500Mbps
- Tucson, AZ - Remote NAS (Setillo)
- Remote (behind Beryl 7) - jellyfish + Home Assistant via GL-MT3600BE, subnet
192.168.12.0/24 - Honolulu, HI - Remote/family access (moon)
- Seattle, WA - Cloud VPS (Contabo) — HolyClaude, Stoatchat, DERP relay
Key Infrastructure
- 3 Synology NAS units (Atlantis, Calypso, Setillo)
- 10GbE backbone via TP-Link TL-SX1008
- Headscale mesh (28 nodes) connecting all locations, DERP relays on Atlantis + Seattle
- Proxmox virtualization for VMs
- Authentik SSO protecting 12+ services
- Nginx Proxy Manager on matrix-ubuntu (wildcard LE certs via acme.sh)
- Olares K3s node for local LLM inference (RTX 5090)
- GL-MT3600BE (Beryl 7) remote primary gateway; GL-MT3000 (Beryl AX) and GL-BE3600 (Slate 7) as travel routers (exit-node only)
Service Counts by Host (verified 2026-04-18)
| Host | Containers | Primary Role |
|---|---|---|
| Atlantis | 59 | Media, downloads, arr-suite, AnythingLLM |
| Calypso | 61 | Auth (Authentik), Headscale, Immich, Paperless, Reactive Resume |
| Homelab VM | 37 | Monitoring, Dashboard, NetBox, Semaphore, Perplexica |
| Concord NUC | 22 | Home Assistant, Plex, edge services |
| Seattle VPS | 20 | HolyClaude, LiveKit, Stoatchat, DERP, Obsidian |
| Guava (TrueNAS) | 19 | Tdarr node, Ollama, OpenWebUI, planka, portainer (standalone) |
| matrix-ubuntu | 12 | NPM, Matrix, Mastodon, LiveKit, CrowdSec |
| RPi 5 (Vish) | 7 | Uptime Kuma, DIUN, dozzle-agent |
| Setillo | 4 | node_exporter, snmp_exporter, secondary AdGuard, dozzle-agent |
| Jellyfish | 2 | Remote photo/media host (behind Beryl 7) |
| Total | ~243 | Across 5 Portainer endpoints + matrix-ubuntu + standalone hosts |
🔄 Diagram Updates
These diagrams should be updated when:
- New hosts are added
- Network topology changes
- Services are added/removed
- Storage configuration changes
- Authentication flows change
📝 Viewing Diagrams
These diagrams render automatically on:
- Gitea (git.vish.gg) - Native Mermaid support
- GitHub - Native Mermaid support
- VS Code - With Mermaid extension
For local viewing:
# Install mermaid-cli
npm install -g @mermaid-js/mermaid-cli
# Generate PNG from markdown
mmdc -i service-architecture.md -o output.png
Last updated: 2026-04-18