116 lines
4.7 KiB
Markdown
116 lines
4.7 KiB
Markdown
# 📊 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](https://mermaid.js.org/) for rendering.
|
|
|
|
## 📁 Diagram Index
|
|
|
|
| Diagram | Description | Format |
|
|
|---------|-------------|--------|
|
|
| [Network Topology](network-topology.md) | Physical and logical network layout across all locations | Mermaid + ASCII |
|
|
| [Tailscale Mesh](tailscale-mesh.md) | VPN mesh network connecting all locations | Mermaid + ASCII |
|
|
| [10GbE Backbone](10gbe-backbone.md) | High-speed network backbone in Concord | Mermaid + ASCII |
|
|
| [Service Architecture](service-architecture.md) | How services interact, auth flows, CI/CD pipeline | Mermaid |
|
|
| [Storage Topology](storage-topology.md) | NAS cluster, volumes, and backup flows | Mermaid + ASCII |
|
|
| [Location Overview](location-overview.md) | 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:
|
|
```bash
|
|
# 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*
|