# Homelab Documentation Index

Last updated: 2026-03-21

## Quick Start

- [**README.md**](../README.md) — Repository overview
- [**Deploy a New Service**](guides/deploy-new-service-gitops.md) — Compose file to live container (GitOps)
- [**Ansible Playbook Guide**](admin/ANSIBLE_PLAYBOOK_GUIDE.md) — Run playbooks from CLI or Semaphore UI

## Infrastructure

### Core Architecture
- [**Network Topology**](diagrams/network-topology.md) — Physical/logical network, 10GbE backbone, all locations
- [**Service Architecture**](diagrams/service-architecture.md) — Media stack, monitoring, auth, CI/CD, AI/ML
- [**Storage Topology**](diagrams/storage-topology.md) — NAS cluster, ZFS pools, NVMe, Backblaze B2
- [**Tailscale Mesh**](diagrams/tailscale-mesh.md) — 24-node Headscale VPN mesh, exit nodes, DERP relays
- [**10GbE Backbone**](diagrams/10gbe-backbone.md) — High-speed switch connections
- [**Location Overview**](diagrams/location-overview.md) — Geographic distribution (Concord, Tucson, Honolulu, Seattle)
- [**Diagram Index**](diagrams/README.md) — All Mermaid diagrams

### DNS & Reverse Proxy
- [**Split-Horizon DNS**](infrastructure/split-horizon-dns.md) — Dual AdGuard (Calypso + Atlantis), local resolution
- [**Offline & Remote Access**](infrastructure/offline-and-remote-access.md) — LAN, Tailscale, and internet access paths
- [**NPM Migration**](infrastructure/npm-migration-to-matrix-ubuntu.md) — NPM moved to matrix-ubuntu (2026-03-20)
- [**Authentik SSO**](infrastructure/authentik-sso.md) — OAuth2/OIDC providers, forward auth, protected services
- [**Cloudflare DNS**](infrastructure/cloudflare-dns.md) — DNS records and Cloudflare configuration
- [**NPM Migration (Jan 2026)**](infrastructure/npm-migration-jan2026.md) — Historical: Synology proxy to NPM

### Hardware
- [**Hardware Inventory**](infrastructure/hardware-inventory.md) — Complete specs, serial numbers, warranty info
- [**Host Overview**](infrastructure/hosts.md) — Per-host details, IPs, services

## Administration

### Operations
- [**Monitoring Setup**](admin/monitoring-setup.md) — Prometheus (14 targets), Grafana, Alertmanager, ntfy, Uptime Kuma
- [**Alerting Setup**](admin/alerting-setup.md) — ntfy + Signal dual-channel notifications
- [**Image Update Guide**](admin/IMAGE_UPDATE_GUIDE.md) — Renovate, GitOps CI/CD, DIUN, Watchtower
- [**Ansible Playbook Guide**](admin/ANSIBLE_PLAYBOOK_GUIDE.md) — 25 playbooks, Semaphore UI, common workflows
- [**Backup Strategy**](infrastructure/backup-strategy.md) — 3-2-1 rule, Backblaze B2, recovery procedures
- [**Portainer API Guide**](admin/PORTAINER_API_GUIDE.md) — Stack management, container operations

### Security
- [**Secrets Management**](admin/secrets-management.md) — Private repo, public mirror, detect-secrets
- [**Authentik SSO**](infrastructure/authentik-sso.md) — 12+ protected services, OAuth2/OIDC + forward auth
- [**SSH Access Guide**](infrastructure/SSH_ACCESS_GUIDE.md) — SSH key setup, per-host access
- [**User Access Guide**](infrastructure/USER_ACCESS_GUIDE.md) — User management

### GitOps & CI/CD
- [**GitOps Guide**](admin/GITOPS_COMPREHENSIVE_GUIDE.md) — Full GitOps architecture
- [**Deployment Workflow**](admin/DEPLOYMENT_WORKFLOW.md) — 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**](services/VERIFIED_SERVICE_INVENTORY.md) — ~195 containers, verified from Portainer API
- [**Service Categories**](services/categories.md) — Services organized by function
- [**Service Index**](services/index.md) — Alphabetical service list

### Key Service Docs
| Service | Doc | Host | Port |
|---------|-----|------|------|
| NetBox | [netbox.md](services/individual/netbox.md) | homelab-vm | 8443 |
| Grafana | [grafana.md](services/individual/grafana.md) | homelab-vm | 3300 |
| Prometheus | [prometheus.md](services/individual/prometheus.md) | homelab-vm | 9090 |
| LazyLibrarian | [lazylibrarian.md](services/individual/lazylibrarian.md) | Atlantis | 5299 |
| Audiobookshelf | [audiobookshelf.md](services/individual/audiobookshelf.md) | Atlantis | 13378 |
| Bazarr | [bazarr.md](services/individual/bazarr.md) | Atlantis | 6767 |
| Olares | [olares.md](services/individual/olares.md) | Olares | K8s |
| AnythingLLM | [anythingllm.md](services/individual/anythingllm.md) | Atlantis | — |
| Apt-Cacher-NG | [apt-cacher-ng.md](services/individual/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](diagrams/network-topology.md) | Physical connections, 10GbE, ISPs |
| [Service Architecture](diagrams/service-architecture.md) | Media stack, auth, monitoring, CI/CD, AI/ML |
| [Storage Topology](diagrams/storage-topology.md) | NAS volumes, ZFS, NVMe, Backblaze B2 backups |
| [Tailscale Mesh](diagrams/tailscale-mesh.md) | 24-node VPN mesh, exit nodes, DERP |
| [10GbE Backbone](diagrams/10gbe-backbone.md) | Switch connections |
| [Location Overview](diagrams/location-overview.md) | 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

- [Emergency Access](troubleshooting/EMERGENCY_ACCESS_GUIDE.md)
- [Common Issues](troubleshooting/common-issues.md)
- [Container Diagnosis](troubleshooting/CONTAINER_DIAGNOSIS_REPORT.md)

## Recently Updated (March 2026)

| Doc | What changed |
|-----|-------------|
| [Split-Horizon DNS](infrastructure/split-horizon-dns.md) | NEW: Implemented dual AdGuard, LE certs, NPM migration |
| [Offline & Remote Access](infrastructure/offline-and-remote-access.md) | NEW: LAN/VPN/internet access paths, .tail.vish.gg |
| [Backup Strategy](infrastructure/backup-strategy.md) | NEW: Consolidated backup docs, Backblaze B2, recovery |
| [Image Update Guide](admin/IMAGE_UPDATE_GUIDE.md) | NEW: 5-layer update strategy |
| [NPM Migration](infrastructure/npm-migration-to-matrix-ubuntu.md) | NEW: NPM moved to matrix-ubuntu |
| [NetBox](services/individual/netbox.md) | NEW: DCIM deployed with OIDC SSO |
| [Ansible Playbook Guide](admin/ANSIBLE_PLAYBOOK_GUIDE.md) | Rewritten: 25 playbooks, Semaphore UI |
| [Monitoring Setup](admin/monitoring-setup.md) | Updated: 14 targets, ntfy topic, Uptime Kuma |
| [Authentik SSO](infrastructure/authentik-sso.md) | Updated: NetBox OIDC, Wizarr removed |
| [All Diagrams](diagrams/README.md) | Updated: counts, NPM location, Olares, storage NVMe |
| [Service Inventory](services/VERIFIED_SERVICE_INVENTORY.md) | Updated: 195 containers |

---

**Repository**: [git.vish.gg/Vish/homelab](https://git.vish.gg/Vish/homelab)
**Total Documents**: 100+ files
**Dashboard**: [dash.vish.gg](https://dash.vish.gg) (Homarr)
**DCIM**: [nb.vish.gg](https://nb.vish.gg) (NetBox)
**Monitoring**: [gf.vish.gg](https://gf.vish.gg) (Grafana)