8.1 KiB
8.1 KiB
Homelab Documentation Index
Last updated: 2026-03-21
Quick Start
- README.md — Repository overview
- Deploy a New Service — Compose file to live container (GitOps)
- Ansible Playbook Guide — Run playbooks from CLI or Semaphore UI
Infrastructure
Core Architecture
- Network Topology — Physical/logical network, 10GbE backbone, all locations
- Service Architecture — Media stack, monitoring, auth, CI/CD, AI/ML
- Storage Topology — NAS cluster, ZFS pools, NVMe, Backblaze B2
- Tailscale Mesh — 24-node Headscale VPN mesh, exit nodes, DERP relays
- 10GbE Backbone — High-speed switch connections
- Location Overview — Geographic distribution (Concord, Tucson, Honolulu, Seattle)
- Diagram Index — All Mermaid diagrams
DNS & Reverse Proxy
- Split-Horizon DNS — Dual AdGuard (Calypso + Atlantis), local resolution
- Offline & Remote Access — LAN, Tailscale, and internet access paths
- NPM Migration — NPM moved to matrix-ubuntu (2026-03-20)
- Authentik SSO — OAuth2/OIDC providers, forward auth, protected services
- Cloudflare DNS — DNS records and Cloudflare configuration
- NPM Migration (Jan 2026) — Historical: Synology proxy to NPM
Hardware
- Hardware Inventory — Complete specs, serial numbers, warranty info
- Host Overview — Per-host details, IPs, services
Administration
Operations
- Monitoring Setup — Prometheus (14 targets), Grafana, Alertmanager, ntfy, Uptime Kuma
- Alerting Setup — ntfy + Signal dual-channel notifications
- Image Update Guide — Renovate, GitOps CI/CD, DIUN, Watchtower
- Ansible Playbook Guide — 25 playbooks, Semaphore UI, common workflows
- Backup Strategy — 3-2-1 rule, Backblaze B2, recovery procedures
- Portainer API Guide — Stack management, container operations
Security
- Secrets Management — Private repo, public mirror, detect-secrets
- Authentik SSO — 12+ protected services, OAuth2/OIDC + forward auth
- SSH Access Guide — SSH key setup, per-host access
- User Access Guide — User management
GitOps & CI/CD
- GitOps Guide — Full GitOps architecture
- Deployment Workflow — Git push to auto-deploy pipeline
- CI Runners: 3 Gitea runners (homelab, calypso, pi5) with
pythonlabel - Workflows:
validate.yml,portainer-deploy.yml,mirror-to-public.yaml,dns-audit.yml,renovate.yml
Services
Inventory
- Verified Service Inventory — ~195 containers, verified from Portainer API
- Service Categories — Services organized by function
- Service Index — Alphabetical service list
Key Service Docs
| Service | Doc | Host | Port |
|---|---|---|---|
| NetBox | netbox.md | homelab-vm | 8443 |
| Grafana | grafana.md | homelab-vm | 3300 |
| Prometheus | prometheus.md | homelab-vm | 9090 |
| LazyLibrarian | lazylibrarian.md | Atlantis | 5299 |
| Audiobookshelf | audiobookshelf.md | Atlantis | 13378 |
| Bazarr | bazarr.md | Atlantis | 6767 |
| Olares | olares.md | Olares | K8s |
| AnythingLLM | anythingllm.md | Atlantis | — |
| Apt-Cacher-NG | apt-cacher-ng.md | Calypso | 3142 |
New Services (added 2026-03-20/21)
| Service | Host | Port | Purpose |
|---|---|---|---|
| SearXNG | homelab-vm | 8888 | Privacy meta search engine |
| Semaphore UI | homelab-vm | 3838 | Ansible web UI (25 playbook templates) |
| Excalidraw | homelab-vm | 5080 | Collaborative whiteboard |
| NetBox | homelab-vm | 8443 | DCIM/IPAM (19 devices, 110 services) |
| AdGuard (backup) | Atlantis | 9080 | Backup split-horizon DNS |
Diagrams
All diagrams use Mermaid.js + ASCII art. View on Gitea (native rendering) or VS Code.
| Diagram | What it shows |
|---|---|
| Network Topology | Physical connections, 10GbE, ISPs |
| Service Architecture | Media stack, auth, monitoring, CI/CD, AI/ML |
| Storage Topology | NAS volumes, ZFS, NVMe, Backblaze B2 backups |
| Tailscale Mesh | 24-node VPN mesh, exit nodes, DERP |
| 10GbE Backbone | Switch connections |
| Location Overview | Concord, Tucson, Honolulu, Seattle |
Hosts
| Host | Role | LAN IP | Tailscale IP | Containers |
|---|---|---|---|---|
| Atlantis | Primary NAS | 192.168.0.200 | 100.83.230.112 | 59 |
| Calypso | Secondary NAS | 192.168.0.250 | 100.103.48.78 | 61 |
| matrix-ubuntu | NPM, Matrix | 192.168.0.154 | 100.85.21.51 | 12+ |
| homelab-vm | Monitoring, tools | 192.168.0.210 | 100.67.40.126 | 38 |
| Concord NUC | Edge, HA | 192.168.68.100 | 100.72.55.21 | 19 |
| RPi 5 | Uptime Kuma | 192.168.0.66 | 100.77.151.40 | 6 |
| Guava | TrueNAS | 192.168.0.100 | 100.75.252.64 | — |
| Olares | K8s, LLM | 192.168.0.145 | — | ~60 pods |
| Setillo | Remote NAS | — | 100.125.0.20 | 4 |
| Seattle | Cloud VPS | — | 100.82.197.124 | 7 |
| PVE | Hypervisor | 192.168.0.205 | 100.87.12.28 | — |
Troubleshooting
Recently Updated (March 2026)
| Doc | What changed |
|---|---|
| Split-Horizon DNS | NEW: Implemented dual AdGuard, LE certs, NPM migration |
| Offline & Remote Access | NEW: LAN/VPN/internet access paths, .tail.vish.gg |
| Backup Strategy | NEW: Consolidated backup docs, Backblaze B2, recovery |
| Image Update Guide | NEW: 5-layer update strategy |
| NPM Migration | NEW: NPM moved to matrix-ubuntu |
| NetBox | NEW: DCIM deployed with OIDC SSO |
| Ansible Playbook Guide | Rewritten: 25 playbooks, Semaphore UI |
| Monitoring Setup | Updated: 14 targets, ntfy topic, Uptime Kuma |
| Authentik SSO | Updated: NetBox OIDC, Wizarr removed |
| All Diagrams | Updated: counts, NPM location, Olares, storage NVMe |
| Service Inventory | Updated: 195 containers |
Repository: git.vish.gg/Vish/homelab Total Documents: 100+ files Dashboard: dash.vish.gg (Homarr) DCIM: nb.vish.gg (NetBox) Monitoring: gf.vish.gg (Grafana)