From 2bbdd21bd34b1221a404974e72b93c3cf81fca72 Mon Sep 17 00:00:00 2001 From: Storme-bit Date: Sun, 5 Apr 2026 01:37:01 -0700 Subject: [PATCH] Added homelab documentation --- docs/homelab/overview.md | 254 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 254 insertions(+) create mode 100644 docs/homelab/overview.md diff --git a/docs/homelab/overview.md b/docs/homelab/overview.md new file mode 100644 index 0000000..9ff6344 --- /dev/null +++ b/docs/homelab/overview.md @@ -0,0 +1,254 @@ +# 🏠 Homelab Documentation + +> **Status:** Phase 1 Complete → Phase 2 In Progress +> **Last Updated:** April 2026 + +--- + +## Table of Contents + +1. [Overview](#overview) +2. [Hardware](#hardware) +3. [Network & Access](#network--access) +4. [Infrastructure Node — Mini PC 2](#infrastructure-node--mini-pc-2) +5. [Media Node — Mini PC 1](#media-node--mini-pc-1) +6. [Main PC](#main-pc) +7. [Storage Layout](#storage-layout) +8. [Reverse Proxy — Caddy](#reverse-proxy--caddy) +9. [Phase 1 Summary](#phase-1-summary) +10. [Phase 2 Roadmap](#phase-2-roadmap) + +--- + +## Overview + +This homelab is a self-hosted, multi-node setup running across three machines on a local network. It is designed around modularity and separation of concerns: + +- **Mini PC 2** acts as the infrastructure manager — handling networking, authentication, monitoring, DNS, and git hosting. +- **Mini PC 1** acts as the media and services workhorse — running the arr stack, Jellyfin, Nextcloud, NexusAI dependencies, and download management. +- **Main PC** is the primary inference node, housing the RTX A4000 GPU for AI workloads. + +All external access is routed through **Caddy** (reverse proxy) with **Authelia** providing SSO/MFA, and **Tailscale** for secure remote access. **Pihole** handles local DNS. + +--- + +## Hardware + +### Main PC +| Spec | Detail | +|------|--------| +| GPU | NVIDIA RTX A4000 | +| Role | Primary AI inference node | +| Key Services | Ollama (inference) | + +### Mini PC 1 — Media Node (`192.168.0.81`) +| Spec | Detail | +|------|--------| +| GPU | NVIDIA RTX 5050 | +| Role | Media services, embeddings, vector storage | +| Key Services | Jellyfin, Nextcloud, Qdrant, arr stack, NexusAI memory/embedding | +| Storage | NVMe (OS) + 3x external HDDs (see [Storage Layout](#storage-layout)) | + +### Mini PC 2 — Infrastructure Node (`192.168.0.205`) +| Spec | Detail | +|------|--------| +| Role | Network management, monitoring, auth, DNS, git | +| Key Services | Caddy, Authelia, Tailscale, Pihole, Grafana, Gitea | +| Storage | NVMe (OS only) | + +--- + +## Network & Access + +| Component | Tool | Notes | +|-----------|------|-------| +| Reverse Proxy | Caddy | Handles HTTPS termination for all services | +| Authentication | Authelia | SSO + MFA for protected services | +| Remote Access | Tailscale | Secure VPN mesh for remote connectivity | +| DNS | Pihole | Local DNS resolution + ad blocking | +| Git Hosting | Gitea | Self-hosted at `192.168.0.205:3100` | + +> **Note:** Gitea has SSO bypassed — it uses its own auth. All other externally exposed services are protected behind Authelia. + +--- + +## Infrastructure Node — Mini PC 2 + +**IP:** `192.168.0.205` + +### Containers + +| Container | Port | Stack | Notes | +|-----------|------|-------|-------| +| caddy | 80, 443 | network | Reverse proxy, HTTPS termination | +| authelia | 9091 | network | SSO / MFA provider | +| tailscale | — | network | Mesh VPN | +| pihole | — | dns | Local DNS + ad blocking | +| prometheus | 9090 | monitoring | Metrics scraping | +| grafana | 3002 | monitoring | Dashboards | +| uptime-kuma | 3001 | monitoring | Uptime monitoring | +| node_exporter | 9100 | monitoring | Host metrics | +| cadvisor | 8088 | monitoring | Container metrics | +| prowlarr | 9696 | indexing | Indexer manager | +| flaresolverr | 8191 | indexing | Cloudflare bypass for indexers | +| homepage | 3000 | homepage | Service dashboard | +| gitea | 3100 | gitea | Self-hosted git | +| portainer | 9000 | — | Container management (primary) | + +--- + +## Media Node — Mini PC 1 + +**IP:** `192.168.0.81` + +### Containers + +#### Media Apps +| Container | Port | Stack | Notes | +|-----------|------|-------|-------| +| jellyfin | 8096 | mediaapps | Media streaming server | +| seer | 5055 | mediaapps | Request management (Overseerr/Jellyseerr) | +| kavita | 5000 | mediaapps | Comics / manga / ebook reader | + +#### Arr Stack +| Container | Port | Stack | Notes | +|-----------|------|-------|-------| +| radarr | 7878 | arrstack | Movie management | +| radarr-anime | 7877 | arrstack | Anime movie management | +| sonarr | 8989 | arrstack | TV show management | +| sonarr-anime | 8988 | arrstack | Anime series management | +| whisparr | 6969 | arrstack | Adult content management | +| bazarr | 6767 | arrstack | Subtitle management | +| suwayomi | 4567 | arrstack | Manga reader / downloader | + +#### Download Core +| Container | Port | Stack | Notes | +|-----------|------|-------|-------| +| gluetun | 8080 | download_core | VPN container — qBittorrent routes through this | +| qbittorrent | (via gluetun) | download_core | Torrent client, traffic tunnelled through Gluetun | + +#### Cloud & Tools +| Container | Port | Stack | Notes | +|-----------|------|-------|-------| +| nextcloud (AIO) | — | — | Self-hosted cloud storage suite | +| filebrowser | 8085 | home_tools | Web-based file management | +| couchdb-obsidian-livesync | 5984 | obsidian | CouchDB backend for Obsidian LiveSync | + +#### NexusAI +| Container | Port | Stack | Notes | +|-----------|------|-------|-------| +| qdrant | 6333 | nexusai | Vector database for NexusAI memory service | + +#### Monitoring & Management +| Container | Port | Stack | Notes | +|-----------|------|-------|-------| +| node_exporter | 9100 | monitoring | Host metrics | +| cadvisor | 8088 | monitoring | Container metrics | +| nvidia_smi_exporter | 9835 | — | GPU metrics (RTX 5050) | +| portainer_agent | 9001 | — | Managed by Portainer on Mini PC 2 | + +--- + +## Main PC + +**Role:** Primary AI inference node + +| Service | Notes | +|---------|-------| +| Ollama | Runs LLM inference using the RTX A4000. Also serves `nomic-embed-text` embeddings (768-dim vectors) consumed by NexusAI's embedding service on Mini PC 1. | + +--- + +## Storage Layout + +### Mini PC 2 (Infrastructure Node) +| Device | Size | Mount | Notes | +|--------|------|-------|-------| +| sda | 238.5G | — | Primary disk | +| sda1 | 1G | /boot/efi | EFI partition | +| sda2 | 2G | /boot | Boot partition | +| sda3 → LVM | 100G | / | OS root via LVM | + +### Mini PC 1 (Media Node) +| Device | Size | Mount | Notes | +|--------|------|-------|-------| +| nvme0n1p1 | 1G | /boot/efi | EFI partition | +| nvme0n1p2 | 464.7G | / | OS root (NVMe) | +| sda1 | 10.9T | /mnt/media-anime | External HDD — anime media | +| sdb1 | 7.3T | /mnt/media-main | External HDD — main media library | +| sdc1 | 7.3T | /mnt/seedbox | External HDD — seedbox/download staging | + +> **Total external storage on Mini PC 1:** ~25.5TB across 3 drives + +--- + +## Reverse Proxy — Caddy + +All services are accessed via subdomains proxied through Caddy on Mini PC 2. Authelia middleware is applied to most services. Gitea is exempt from SSO. + +```caddy +# ============================================================ +# Caddyfile — redacted for documentation +# Full config lives at [REDACTED PATH] on Mini PC 2 +# ============================================================ + +# --- Authelia forward auth snippet --- +(authelia) { + forward_auth authelia:9091 { + uri /api/verify?rd=https://auth.[DOMAIN] + copy_headers Remote-User Remote-Groups Remote-Name Remote-Email + } +} + +# --- Example: SSO-protected service --- +service.[DOMAIN] { + import authelia + reverse_proxy [HOST]:[PORT] +} + +# --- Example: Public / SSO-exempt service (e.g. Gitea) --- +git.[DOMAIN] { + reverse_proxy 192.168.0.205:3100 +} + +# --- Example: Internal-only service --- +grafana.[DOMAIN] { + import authelia + reverse_proxy 192.168.0.205:3002 +} +``` + +> Actual subdomains, domain name, and internal IPs beyond what's documented above are redacted. + +--- + +## Phase 1 Summary + +Phase 1 focused on establishing a stable, secure, and observable foundation: + +- ✅ Reverse proxy with HTTPS (Caddy) +- ✅ SSO & MFA across services (Authelia) +- ✅ Secure remote access (Tailscale) +- ✅ Local DNS & ad blocking (Pihole) +- ✅ Full monitoring stack (Prometheus + Grafana + Uptime Kuma + exporters) +- ✅ Self-hosted git (Gitea) +- ✅ Media stack fully operational (Jellyfin, arr stack, Nextcloud) +- ✅ Download pipeline with VPN isolation (Gluetun + qBittorrent) +- ✅ NexusAI foundation services running (Qdrant, Ollama) +- ✅ Container management across nodes (Portainer + agent) + +--- + +## Phase 2 Roadmap + +Phase 2 shifts focus to resilience, security hardening, and smart home integration. + +### Priorities + +- **Backup improvements** — Formalize and automate backup strategies for critical data (Nextcloud, databases, configs, media metadata) +- **Additional security hardening** — Audit exposed services, tighten firewall rules, review Authelia policies +- **IP webcam integration** — Add camera feeds into the homelab ecosystem +- **Home Assistant** — Integrate smart home automation and sensor data +- **Continued NexusAI development** — Entities layer, embedding service, inference and orchestration buildout + +> This section will be expanded as Phase 2 planning matures. \ No newline at end of file