homelab-optimized/docs/INDEX.md

Homelab Documentation Index

Last updated: 2026-04-18

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 — 28-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 python label
• Workflows: validate.yml, portainer-deploy.yml, mirror-to-public.yaml, dns-audit.yml, renovate.yml

Services

Inventory

• Verified Service Inventory — ~240 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	—
HolyClaude	holyclaude.md	Seattle	3059
Dashboard	dashboard.md	homelab-vm	3100
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	28-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 (Synology)	192.168.0.200	100.83.230.112	59
Calypso	Secondary NAS (Synology, DNS/SSO)	192.168.0.250	100.103.48.78	61
matrix-ubuntu	NPM, Matrix, CrowdSec	192.168.0.154	100.85.21.51	12
homelab-vm	Monitoring, dashboard, tools	192.168.0.210	100.67.40.126	37
Concord NUC	Edge, HA	192.168.68.100	100.72.55.21	22
RPi 5	Uptime Kuma	192.168.0.66	100.77.151.40	7
Guava	TrueNAS SCALE, tdarr-node	192.168.0.100	100.75.252.64	19
Olares	K3s, RTX 5090 LLM/Jellyfin	192.168.0.145	—	~60 pods
Setillo	Remote Synology (DS223j, secondary AdGuard)	—	100.125.0.20	4
Seattle	Cloud VPS (HolyClaude, Matrix LiveKit, derper)	YOUR_WAN_IP	100.82.197.124	20
Jellyfish	Remote workstation (LAN backup, router behind Beryl 7)	—	100.69.121.120	2
PVE	Proxmox hypervisor	192.168.0.205	100.87.12.28	—

Troubleshooting

• Emergency Access
• Common Issues
• Container Diagnosis

Recently Updated

April 2026

Doc	What changed
Jellyfish host	NEW: Remote workstation with GL-MT3600BE (Beryl 7) gateway
Setillo host	NEW: DS223j with Entware + sudoers workaround
HolyClaude	NEW: AI coding workstation on Seattle VPS (port 3059)
Dashboard	NEW: Next.js+FastAPI homelab dashboard, 16 themes
AnythingLLM	Reverted to qwen3-coder:latest (avoid REDACTED_APP_PASSWORD jobs)
Olares	qwen3:32b migration + revert history; Jellyfin + RTX 5090 transcoding
AI Integrations	qwen3-coder → qwen3:32b migration rationale (2026-04-13)
Email digest + organizers	HTML templates, Proton Bridge IMAP Digests folder delivery

March 2026

Doc	What changed
Split-Horizon DNS	Implemented dual AdGuard, LE certs, NPM migration
Offline & Remote Access	LAN/VPN/internet access paths, .tail.vish.gg
Backup Strategy	Consolidated backup docs, Backblaze B2, recovery
Image Update Guide	5-layer update strategy
NPM Migration	NPM moved to matrix-ubuntu
NetBox	DCIM deployed with OIDC SSO
Ansible Playbook Guide	Rewritten: 25 playbooks, Semaphore UI
Monitoring Setup	14 targets, ntfy topic, Uptime Kuma
Authentik SSO	NetBox OIDC, Wizarr removed
Service Inventory	Updated container count

---

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)