commit 7650e6f4598f92fdab8f934f942b6202352e01b5 Author: Chase Dumphord Date: Mon Dec 8 22:17:44 2025 -0600 Initial commit: Ced's HomeLab docs and structure diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..bddacf9 --- /dev/null +++ b/.gitignore @@ -0,0 +1,33 @@ +# OS / Editor junk +.DS_Store +Thumbs.db +*.swp +*.swo + +# Node / Python / etc (future-proofing) +node_modules/ +venv/ +.env + +# Secrets (DO NOT COMMIT!) +*.pem +*.key +*.crt +*.pfx +*.json +secrets.yaml +secret.yaml +*.kubeconfig + +# Home Assistant internal data +home-assistant/.storage/ +home-assistant/.cloud/ + +# Terraform / Ansible (if you add later) +*.tfstate +*.tfstate.backup +.terraform/ + +# IDE +.vscode/ +.idea/ diff --git a/README.md b/README.md new file mode 100644 index 0000000..48ea12d --- /dev/null +++ b/README.md @@ -0,0 +1,153 @@ +# Ced's HomeLab + +Ced's HomeLab is my personal mini–datacenter: a segmented, cloud-connected environment built for learning, experimentation, and portfolio work. It includes: + +- Proxmox virtualization +- TrueNAS ZFS storage +- A 12-node Raspberry Pi K3s cluster +- Nginx Proxy Manager + Cloudflare Tunnel +- Home Assistant + IoT integration +- Media stack (Arr suite + Jellyfin) +- Observability (Grafana, Prometheus, Uptime Kuma) + +This repo is the **documentation and configuration hub** for the entire environment. + +--- + +## 🌐 Network & VLANs + +The lab runs behind a UniFi Dream Router (UDR) with VLAN segmentation: + +| Network | Subnet | Purpose | +|--------------|----------------|---------------------------------| +| Main | 10.10.10.0/24 | Daily-use devices | +| MyHomeIOT | 10.10.20.0/24 | IoT devices, TVs, consoles | +| HomeLab | 10.10.30.0/24 | Servers, services, K3s, storage | +| Guest | 10.10.99.0/24 | Guest Wi-Fi | + +The HomeLab VLAN (10.10.30.0/24) hosts all core infrastructure. + +--- + +## 🧱 Core Components + +### Proxmox VE + +- Main hypervisor for VMs and LXCs +- Future expansion to a Proxmox cluster (+5 nodes) +- Uses TrueNAS for shared storage (NFS / iSCSI) + +See: [`proxmox/`](proxmox/) + +--- + +### TrueNAS (ZFS Storage) + +- Manages ZFS pools and datasets +- NFS exports for Proxmox VM storage +- SMB / media dataset for Jellyfin & Arr stack + +See: [`truenas/`](truenas/) + +--- + +### K3s Raspberry Pi Cluster + +A 12-node K3s cluster (Raspberry Pis) for running: + +- Containerized apps +- Ingress-based routing +- GitOps and helm-based workloads (future) + +K3s is part of the HomeLab but documented in detail in its own repo: +- https://github.com/ced4568/ced-k3s-homelab + +This repo may reference that cluster and contain high-level config patterns. + +--- + +### Reverse Proxy & Cloudflare Tunnel + +- Nginx Proxy Manager (NPM) on the HomeLab VLAN +- Cloudflare Tunnel (no port forwarding) +- Wildcard DNS: `*.cedshomelab.com` + +External access flow: + +```text +Internet β†’ Cloudflare Edge β†’ Tunnel β†’ NPM β†’ Internal Services +``` + +Docs: [`docs/Add_New_Service_Guide.md`](docs/Add_New_Service_Guide.md) + +--- + +### Home Automation + +- Home Assistant (HA) in Proxmox +- IoT devices isolated on MyHomeIOT VLAN +- HA exposed via Cloudflare + NPM +- `trusted_proxies` configured for NPM + +Config snippets: [`home-assistant/configuration-snippets/`](home-assistant/configuration-snippets/) + +--- + +### Observability + +- Prometheus scrapes metrics from: + - Proxmox + - K3s + - TrueNAS (future) + - Home Assistant / MQTT (future) +- Grafana dashboards, including a **Ced's NOC** view +- Uptime Kuma for service-level monitoring + +Notes and dashboards: [`monitoring/`](monitoring/) + +--- + +## 🧭 Documentation + +- **How to add a new service via NPM + Cloudflare** + [`docs/Add_New_Service_Guide.md`](docs/Add_New_Service_Guide.md) + +- **Architecture diagrams (Mermaid)** + [`docs/Ced_Homelab_Diagrams.md`](docs/Ced_Homelab_Diagrams.md) + +- **Roadmap / future ideas** + [`docs/roadmap.md`](docs/roadmap.md) + +--- + +## πŸš€ Future Plans + +- Full Proxmox cluster +- Cloudflare Zero Trust on critical services +- GitOps for K3s deployments (in ced-k3s-homelab) +- Internal container registry +- K3s-specific wildcard routing (`*.apps.cedshomelab.com`) +- More detailed monitoring + alerting +- Visual portfolio site on: + - `chasedumphord.com` or + - `cedshome.com` + +--- + +## ⚠️ Secrets & Security + +This repo **never** stores: + +- API tokens +- Private keys +- Passwords +- Secret YAML files + +Any real config with secrets should be kept locally only, or represented here as `*.example` files. + +--- + +## ✨ Author + +**Ced (Chase Dumphord)** +Cybersecurity / GRC / SOC β€’ Full-Stack Dev β€’ Homelab builder diff --git a/ceds-homelab.zip b/ceds-homelab.zip new file mode 100644 index 0000000..5d8f3d1 Binary files /dev/null and b/ceds-homelab.zip differ diff --git a/cloudflare/tunnel-config.example.yml b/cloudflare/tunnel-config.example.yml new file mode 100644 index 0000000..005cf6b --- /dev/null +++ b/cloudflare/tunnel-config.example.yml @@ -0,0 +1,23 @@ +# Example cloudflared config for Ced's HomeLab +# DO NOT PUT REAL CREDENTIALS HERE + +tunnel: YOUR-TUNNEL-ID-HERE +credentials-file: /root/.cloudflared/YOUR-TUNNEL-ID-HERE.json + +ingress: + - hostname: dashy.cedshomelab.com + service: http://10.10.30.210:4000 + + - hostname: pve.cedshomelab.com + service: https://10.10.30.250:8006 + + - hostname: truenas.cedshomelab.com + service: https://10.10.30.143:443 + + - hostname: ha.cedshomelab.com + service: http://10.10.30.104:8123 + + - hostname: "*.cedshomelab.com" + service: http://10.10.30.210:80 + + - service: http_status:404 diff --git a/docs/Add_New_Service_Guide.md b/docs/Add_New_Service_Guide.md new file mode 100644 index 0000000..0af6326 --- /dev/null +++ b/docs/Add_New_Service_Guide.md @@ -0,0 +1,134 @@ +# Adding a New Service to Cloudflare Tunnel + NGINX Proxy Manager + +## Architecture Flow + +```text +Browser + β”‚ + β–Ό +Cloudflare DNS (cedshomelab.com) + β”‚ + β–Ό +Cloudflare Edge (SSL, Zero Trust) + β”‚ + β–Ό +Cloudflare Tunnel (cloudflared) + β”‚ + β–Ό +NGINX Proxy Manager (10.10.30.210) + β”‚ + β–Ό +Internal Service (10.10.30.X:PORT) +``` + +--- + +## Step-By-Step Checklist + +### 1. Gather Service Info + +- **Subdomain:** `service.cedshomelab.com` +- **Internal IP:** `10.10.30.X` +- **Port:** `PORT` +- **Scheme:** `http` or `https` + +Test local access: +- LAN: `http://10.10.30.X:PORT` + +--- + +### 2. (Optional) Create DNS Route in Tunnel + +Inside NPM container: + +```bash +cloudflared tunnel route dns npm-tunnel service.cedshomelab.com +``` + +--- + +### 3. Add Proxy Host in NGINX Proxy Manager + +Open NPM: `http://10.10.30.210:81` + +Go to: +**Hosts β†’ Proxy Hosts β†’ Add Proxy Host** + +**Details tab:** + +- **Domain Names:** `service.cedshomelab.com` +- **Scheme:** `http` or `https` +- **Forward Hostname/IP:** `10.10.30.X` +- **Forward Port:** `PORT` + +Enable: +- Block Common Exploits +- Websockets Support + +--- + +### 4. HTTPS Self-Signed Backends (Optional) + +If backend uses self-signed HTTPS (e.g., Proxmox, TrueNAS): + +In NPM **Advanced tab:** + +```nginx +proxy_ssl_verify off; +proxy_ssl_verify_depth 1; +proxy_ssl_name 10.10.30.X; +``` + +--- + +### 5. SSL Tab + +Since Cloudflare provides SSL: + +- **SSL Certificate:** `None` +- Force SSL: Off +- HSTS: Off +- HTTP/2: Off + +Save. + +--- + +### 6. Test External Access + +Open: +`https://service.cedshomelab.com` + +If issues: +- 404: hostname not in ingress +- 502/504: NPM can’t reach backend +- Cloudflare 52x: tunnel or DNS issue + +--- + +## Notes + +- Wildcard routing `*.cedshomelab.com` sends all new subdomains to NPM automatically. +- Only NPM needs to be updated for new services. +- No need to open router ports. + +--- + +## Example + +For Jellyfin on `http://10.10.30.143:30013`: + +```bash +cloudflared tunnel route dns npm-tunnel jellyfin.cedshomelab.com +``` + +In NPM: +- Domain: `jellyfin.cedshomelab.com` +- Scheme: `http` +- IP: `10.10.30.143` +- Port: `30013` +- Block Exploits: On +- Websockets: On + +Save & test: +`https://jellyfin.cedshomelab.com` diff --git a/docs/Ced_Homelab_Diagrams.md b/docs/Ced_Homelab_Diagrams.md new file mode 100644 index 0000000..97a6c8e --- /dev/null +++ b/docs/Ced_Homelab_Diagrams.md @@ -0,0 +1,177 @@ +# Ced's HomeLab – Network & Cloud Architecture Diagrams + +This file contains **Mermaid diagrams** for: + +- Cloud & homelab architecture +- VLAN segmentation +- Request flows (Proxmox, Home Assistant) + +You can view or edit them with: +- Mermaid Live Editor: https://mermaid.live +- Draw.io (Arrange β†’ Insert β†’ Advanced β†’ Mermaid) +- GitHub / Obsidian / VS Code (Mermaid support) + +--- + +## 1. High-Level Cloud & Homelab Architecture + +```mermaid +graph TD + subgraph Internet["🌐 Internet"] + User[User Browser] + end + + subgraph Cloudflare["Cloudflare Edge"] + CF_DNS[DNS & SSL] + CF_ZT[Zero Trust (future)] + end + + subgraph Tunnel["Cloudflare Tunnel"] + CF_Tunnel[cloudflared
NPM LXC] + end + + subgraph HomeLab_VLAN["HomeLab VLAN 10.10.30.0/24"] + NPM[Nginx Proxy Manager
10.10.30.210] + PVE[Proxmox VE Host
10.10.30.250] + TRUENAS[TrueNAS & Media
10.10.30.143] + HA[Home Assistant
10.10.30.104] + + subgraph K3S["Raspberry Pi K3s Cluster
12 nodes"] + K3S_M[Masters] + K3S_W[Workers] + end + + subgraph OBS["Observability Stack"] + GRAF[Grafana] + PROM[Prometheus] + UPTK[Uptime Kuma] + end + + subgraph MEDIA["Media & Arr Suite"] + ARR[Sonarr/Radarr/etc.] + JF[Jellyfin] + end + end + + User -->|"https://*.cedshomelab.com"| CF_DNS --> CF_ZT + CF_ZT --> CF_Tunnel --> NPM + + NPM -->|"dashy.cedshomelab.com"| NPM + NPM -->|"pve.cedshomelab.com"| PVE + NPM -->|"truenas.cedshomelab.com"| TRUENAS + NPM -->|"ha.cedshomelab.com"| HA + NPM -->|"jellyfin.cedshomelab.com"| JF + NPM -->|"grafana.cedshomelab.com"| GRAF + NPM -->|"prometheus.cedshomelab.com"| PROM + NPM -->|"uptime.cedshomelab.com"| UPTK + NPM -->|"arr.cedshomelab.com"| ARR + + PVE -.-> OBS + PVE -.-> MEDIA + PVE -.-> K3S + TRUENAS -. Storage .- PVE + TRUENAS -. Media Storage .- JF +``` + +--- + +## 2. VLAN & Network Segmentation Diagram + +```mermaid +flowchart LR + subgraph UDR["UniFi Dream Router (UDR)"] + GW_MAIN["VLAN Main 10.10.10.1"] + GW_IOT["VLAN IoT 10.10.20.1"] + GW_LAB["VLAN HomeLab 10.10.30.1"] + GW_GUEST["VLAN Guest 10.10.99.1"] + end + + subgraph VLAN_MAIN["Main Network 10.10.10.0/24"] + DEV1[Phones / Laptops / PCs] + end + + subgraph VLAN_IOT["MyHomeIOT 10.10.20.0/24"] + IOT1[IoT Devices] + TV[Smart TVs / Consoles] + end + + subgraph VLAN_LAB["Ced's HomeLab 10.10.30.0/24"] + PVE[Proxmox Host(s)] + NPM[Nginx Proxy Manager
+ cloudflared] + TRUENAS[TrueNAS] + HA[Home Assistant] + K3S["K3s Pi Cluster"] + OBS[Grafana / Prometheus / Uptime Kuma] + MEDIA[Arr Suite / Jellyfin] + end + + subgraph VLAN_GUEST["Guest Network 10.10.99.0/24"] + GUEST_DEV[Guest Devices] + end + + UDR --- VLAN_MAIN + UDR --- VLAN_IOT + UDR --- VLAN_LAB + UDR --- VLAN_GUEST + + VLAN_MAIN -->|Restricted Access| VLAN_LAB + VLAN_IOT -->|HA API Only| HA + VLAN_GUEST -->|Internet Only| UDR + + VLAN_LAB -->|Cloudflare Tunnel
Outbound Only| NPM +``` + +--- + +## 3. Request Flow – Proxmox via `pve.cedshomelab.com` + +```mermaid +sequenceDiagram + participant User as User Browser + participant CF as Cloudflare Edge + participant Tunnel as cloudflared (NPM LXC) + participant NPM as Nginx Proxy Manager + participant PVE as Proxmox (10.10.30.250:8006) + + User->>CF: HTTPS GET pve.cedshomelab.com + CF->>CF: DNS resolve / SSL terminate / (Zero Trust auth) + CF-->>Tunnel: Encrypted Tunnel Connection + Tunnel-->>NPM: HTTP request (Host: pve.cedshomelab.com) + NPM->>PVE: HTTPS to 10.10.30.250:8006
proxy headers + PVE-->>NPM: Proxmox login HTML + NPM-->>Tunnel: Response + Tunnel-->>CF: Encrypted tunnel response + CF-->>User: HTTPS response (Proxmox UI) +``` + +--- + +## 4. Request Flow – Home Assistant via `ha.cedshomelab.com` + +```mermaid +sequenceDiagram + participant User as User (Phone/Laptop) + participant CF as Cloudflare Edge + participant Tunnel as cloudflared (NPM LXC) + participant NPM as Nginx Proxy Manager + participant HA as Home Assistant (10.10.30.104:8123) + + User->>CF: HTTPS GET ha.cedshomelab.com + CF->>CF: DNS / SSL / (Zero Trust future) + CF-->>Tunnel: Encrypted tunnel connection + Tunnel-->>NPM: HTTP request with X-Forwarded-For + NPM->>HA: HTTP to 10.10.30.104:8123 + HA->>HA: Check trusted_proxies & use_x_forwarded_for + HA-->>NPM: HA UI / API response + NPM-->>Tunnel: Response + Tunnel-->>CF: Response + CF-->>User: HTTPS response (HA UI) +``` + +--- + +## 5. Notes + +- Cloudflare Zero Trust can be layered in front of any critical service. +- External entrypoint is always `*.cedshomelab.com`. +- Only outbound traffic from the HomeLab VLAN is required. diff --git a/docs/homelab_notes.md b/docs/homelab_notes.md new file mode 100644 index 0000000..9e6bc87 --- /dev/null +++ b/docs/homelab_notes.md @@ -0,0 +1,5 @@ +# Homelab Notes + +Freeform scratchpad for commands, quick fixes, and ideas. + +- TODO: add commonly used Proxmox, K3s, and TrueNAS commands here. diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..3005db3 --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,33 @@ +# Ced's HomeLab Roadmap + +## Short Term + +- Document current services and IPs +- Export Grafana "Ced's NOC" dashboard JSON +- Add Prometheus scrape configs for: + - Proxmox + - K3s + - TrueNAS +- Set up standardized NPM host naming + +## Medium Term + +- Build `*.apps.cedshomelab.com` routing for K3s +- Add Cloudflare Zero Trust in front of: + - Proxmox + - TrueNAS + - Grafana + - Home Assistant +- Set up backup strategies: + - Proxmox β†’ TrueNAS + - TrueNAS snapshots + +## Long Term + +- Full Proxmox cluster with HA +- GitOps flows for K3s (ArgoCD or Flux) +- Internal Docker/OCI registry +- Portfolio site hosted on: + - `chasedumphord.com` or + - `cedshome.com` +- More detailed, automated documentation diff --git a/home-assistant/configuration-snippets/http_trusted_proxies.yaml b/home-assistant/configuration-snippets/http_trusted_proxies.yaml new file mode 100644 index 0000000..cdfd3bb --- /dev/null +++ b/home-assistant/configuration-snippets/http_trusted_proxies.yaml @@ -0,0 +1,4 @@ +http: + use_x_forwarded_for: true + trusted_proxies: + - 10.10.30.210 # NPM container IP diff --git a/home-assistant/notes.md b/home-assistant/notes.md new file mode 100644 index 0000000..8b3cc63 --- /dev/null +++ b/home-assistant/notes.md @@ -0,0 +1,3 @@ +# Home Assistant Notes + +- Integrations, automations, and VLAN/IOT-related considerations go here. diff --git a/k3s/README.md b/k3s/README.md new file mode 100644 index 0000000..dc391b0 --- /dev/null +++ b/k3s/README.md @@ -0,0 +1,23 @@ +# K3s Cluster (Raspberry Pi) + +This folder documents how the Raspberry Pi K3s cluster fits into Ced's HomeLab. + +The detailed manifests and cluster-specific configuration live in a separate repo: + +- https://github.com/ced4568/ced-k3s-homelab + +## Goals + +- Learn Kubernetes on real hardware +- Run homelab apps on K3s instead of directly on VMs +- Use Ingress + wildcard DNS for clean routing +- Eventually adopt GitOps workflows + +## Structure (in this repo) + +- `ingresses/` – example host-based ingress rules +- `deployments/` – high-level deployment patterns or sample manifests + +Example target pattern: + +- `myapp.apps.cedshomelab.com` β†’ Traefik Ingress β†’ K3s Service diff --git a/k3s/deployments/.gitkeep b/k3s/deployments/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/k3s/ingresses/.gitkeep b/k3s/ingresses/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/monitoring/grafana-dashboards/.gitkeep b/monitoring/grafana-dashboards/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/monitoring/notes.md b/monitoring/notes.md new file mode 100644 index 0000000..4965fb9 --- /dev/null +++ b/monitoring/notes.md @@ -0,0 +1,3 @@ +# Monitoring Notes + +- Describe Prometheus targets, exporters, and Grafana dashboards here. diff --git a/npm/patterns.md b/npm/patterns.md new file mode 100644 index 0000000..0b2e961 --- /dev/null +++ b/npm/patterns.md @@ -0,0 +1,46 @@ +# Nginx Proxy Manager Patterns + +## General Rules + +- All public services use subdomains on `cedshomelab.com`. +- Cloudflare provides public SSL; NPM usually uses "None" cert internally. +- Backends with self-signed SSL (Proxmox, TrueNAS) use `proxy_ssl_verify off;`. + +## Common Configs + +### Proxmox + +- Domain: `pve.cedshomelab.com` +- Scheme: `https` +- Forward IP: `10.10.30.250` +- Forward Port: `8006` + +**Advanced:** + +```nginx +proxy_ssl_verify off; +proxy_ssl_verify_depth 1; +proxy_ssl_name 10.10.30.250; +``` + +### TrueNAS + +- Domain: `truenas.cedshomelab.com` +- Scheme: `https` +- Forward IP: `10.10.30.143` +- Forward Port: `443` + +**Advanced:** + +```nginx +proxy_ssl_verify off; +proxy_ssl_verify_depth 1; +proxy_ssl_name 10.10.30.143; +``` + +### Home Assistant + +- Domain: `ha.cedshomelab.com` +- Scheme: `http` +- Forward IP: `10.10.30.104` +- Forward Port: `8123` diff --git a/proxmox/notes.md b/proxmox/notes.md new file mode 100644 index 0000000..7ff56b1 --- /dev/null +++ b/proxmox/notes.md @@ -0,0 +1,3 @@ +# Proxmox Notes + +- Document storage configuration, node names, and cluster plans here. diff --git a/truenas/datasets.md b/truenas/datasets.md new file mode 100644 index 0000000..b827878 --- /dev/null +++ b/truenas/datasets.md @@ -0,0 +1,3 @@ +# TrueNAS Datasets + +- List ZFS pools, datasets, and what they are used for.