Initial commit: Ced's HomeLab docs and structure

This commit is contained in:
2025-12-08 22:17:44 -06:00
commit 7650e6f459
18 changed files with 643 additions and 0 deletions
+33
View File
@@ -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/
+153
View File
@@ -0,0 +1,153 @@
# Ced's HomeLab
Ced's HomeLab is my personal minidatacenter: 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
BIN
View File
Binary file not shown.
+23
View File
@@ -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
+134
View File
@@ -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 cant 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`
+177
View File
@@ -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<br/>NPM LXC]
end
subgraph HomeLab_VLAN["HomeLab VLAN 10.10.30.0/24"]
NPM[Nginx Proxy Manager<br/>10.10.30.210]
PVE[Proxmox VE Host<br/>10.10.30.250]
TRUENAS[TrueNAS & Media<br/>10.10.30.143]
HA[Home Assistant<br/>10.10.30.104]
subgraph K3S["Raspberry Pi K3s Cluster<br/>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<br/>+ 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<br/>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<br/>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.
+5
View File
@@ -0,0 +1,5 @@
# Homelab Notes
Freeform scratchpad for commands, quick fixes, and ideas.
- TODO: add commonly used Proxmox, K3s, and TrueNAS commands here.
+33
View File
@@ -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
@@ -0,0 +1,4 @@
http:
use_x_forwarded_for: true
trusted_proxies:
- 10.10.30.210 # NPM container IP
+3
View File
@@ -0,0 +1,3 @@
# Home Assistant Notes
- Integrations, automations, and VLAN/IOT-related considerations go here.
+23
View File
@@ -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
View File
View File
+3
View File
@@ -0,0 +1,3 @@
# Monitoring Notes
- Describe Prometheus targets, exporters, and Grafana dashboards here.
+46
View File
@@ -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`
+3
View File
@@ -0,0 +1,3 @@
# Proxmox Notes
- Document storage configuration, node names, and cluster plans here.
+3
View File
@@ -0,0 +1,3 @@
# TrueNAS Datasets
- List ZFS pools, datasets, and what they are used for.