📊 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

🔐 Key Architecture Components

Authentication & Proxy Stack

┌─────────────────────────────────────────────────────────────────────┐
│  Internet → Cloudflare → NPM (Atlantis) → Authentik (Calypso)       │
│                                ↓                                      │
│                         Protected Services                           │
└─────────────────────────────────────────────────────────────────────┘

Component	Host	Port	Purpose
Nginx Proxy Manager	Atlantis	: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
docs.vish.gg	Paperless-NGX	Forward Auth
photos.vish.gg	Immich	Forward Auth
actual.vish.gg	Actual Budget	Forward Auth
ff.vish.gg	Firefly III	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 8+ services
Nginx Proxy Manager routing 20+ domains

Service Counts by Host

Host	Services	Primary Role
Atlantis	53	Media, monitoring, proxy
Calypso	24	Auth, Gitea, Paperless
Homelab VM	33	Experiments, tools
Concord NUC	11	Edge, Home Assistant
Other hosts	43	Various
Total	164

🔄 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-02-05

4.3 KiB Raw Blame History