4.7 KiB
4.7 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)
- Honolulu, HI - Travel/remote access point
- Seattle, WA - Cloud VPS (Contabo)
Key Infrastructure
- 3 Synology NAS units (Atlantis, Calypso, Setillo)
- 10GbE backbone via TP-Link TL-SX1008
- Tailscale mesh connecting all locations
- Proxmox virtualization for VMs
- Authentik SSO protecting 12+ services
- Nginx Proxy Manager routing 30+ domains
- Olares K8s node for local LLM inference
Service Counts by Host
| Host | Services | Primary Role |
|---|---|---|
| Atlantis | 59 | Media, downloads, DNS backup, dashboard |
| Calypso | 61 | Auth, Gitea, arr-suite, headscale |
| matrix-ubuntu | 12+ | NPM, Matrix, Mastodon, Mattermost |
| Homelab VM | 38 | Monitoring, tools, DCIM, Ansible UI |
| Concord NUC | 19 | Home Assistant, Plex, edge |
| RPi 5 | 6 | Uptime Kuma, monitoring, DIUN |
| Total | ~195 | Across 5 Portainer endpoints + matrix-ubuntu |
🔄 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-03-20