From 7650e6f4598f92fdab8f934f942b6202352e01b5 Mon Sep 17 00:00:00 2001 From: Chase Dumphord Date: Mon, 8 Dec 2025 22:17:44 -0600 Subject: [PATCH] Initial commit: Ced's HomeLab docs and structure --- .gitignore | 33 ++++ README.md | 153 +++++++++++++++ ceds-homelab.zip | Bin 0 -> 10165 bytes cloudflare/tunnel-config.example.yml | 23 +++ docs/Add_New_Service_Guide.md | 134 +++++++++++++ docs/Ced_Homelab_Diagrams.md | 177 ++++++++++++++++++ docs/homelab_notes.md | 5 + docs/roadmap.md | 33 ++++ .../http_trusted_proxies.yaml | 4 + home-assistant/notes.md | 3 + k3s/README.md | 23 +++ k3s/deployments/.gitkeep | 0 k3s/ingresses/.gitkeep | 0 monitoring/grafana-dashboards/.gitkeep | 0 monitoring/notes.md | 3 + npm/patterns.md | 46 +++++ proxmox/notes.md | 3 + truenas/datasets.md | 3 + 18 files changed, 643 insertions(+) create mode 100644 .gitignore create mode 100644 README.md create mode 100644 ceds-homelab.zip create mode 100644 cloudflare/tunnel-config.example.yml create mode 100644 docs/Add_New_Service_Guide.md create mode 100644 docs/Ced_Homelab_Diagrams.md create mode 100644 docs/homelab_notes.md create mode 100644 docs/roadmap.md create mode 100644 home-assistant/configuration-snippets/http_trusted_proxies.yaml create mode 100644 home-assistant/notes.md create mode 100644 k3s/README.md create mode 100644 k3s/deployments/.gitkeep create mode 100644 k3s/ingresses/.gitkeep create mode 100644 monitoring/grafana-dashboards/.gitkeep create mode 100644 monitoring/notes.md create mode 100644 npm/patterns.md create mode 100644 proxmox/notes.md create mode 100644 truenas/datasets.md 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 0000000000000000000000000000000000000000..5d8f3d1a85a12dbab92c7a5c70b274df6a53223a GIT binary patch literal 10165 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 literal 0 HcmV?d00001 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.