This repo is the public-safe tour map for the KeepItTechie homelab. It shows how the lab is put together, why each layer exists, and what readers can learn from running real Linux and open source services at home.
Think of it as a teaching repo, not a config dump. The docs explain the patterns behind pfSense, Pi-hole, Proxmox, storage, backups, monitoring, media workflows, local AI, dashboards, and automation without exposing private infrastructure details.
Current documentation baseline: v0.1.0. See the changelog for release history.
| Start With | Link | Why |
|---|---|---|
| Tour the lab | Current Setup | See what is running and why it exists |
| Build in stages | Build Your Own Homelab | Start small and add one layer at a time |
| Replicate safely | Replication Quickstart | Copy the architecture pattern without copying private details |
| Follow a path | Viewer Guide | Choose the best route through the repo |
| Find everything | Documentation Index | Browse every major guide by topic |
| Learn the terms | Glossary | Look up homelab vocabulary as you read |
| See the map | Diagrams | Follow sanitized architecture and service flows |
| Study examples | Sanitized Examples | Learn safe config patterns without private values |
| Plan visuals | Visual Assets Guide | Prepare safe diagrams, mockups, thumbnails, and future screenshots |
| Browse services | Service Catalog | Pick a service and learn what it does |
The Documentation Index is the deeper table of contents. Use it when you want the service matrix, core infrastructure guide, storage and monitoring guide, apps and AI guide, security notes, release notes, or maintenance docs.
The lab is easier to understand when it is broken into roles instead of treated like one big stack.
| Area | Main Docs | Service Docs |
|---|---|---|
| Network | Core Infrastructure, Network Design | pfSense, Pi-hole, Reverse Proxy, Cloudflare Tunnel |
| Virtualization | Core Infrastructure, Hardware, Public-Safe Inventory, Service Matrix | Proxmox |
| Storage and backups | Storage and Monitoring, Storage and Backups | Synology, ZFS Storage, Proxmox Backup Server |
| Observability | Storage and Monitoring, Service Matrix | Monitoring |
| Media | Apps and AI, Service Matrix | Media Stack |
| Local AI | Apps and AI, Learning Paths | Local AI |
| Documentation and dashboard | Apps and AI, Diagrams | Wiki.js, Glance Dashboard |
| Personal apps | Apps and AI, Security Notes | FinanceHQ, CareerFill |
| Automation | Apps and AI, Maintenance Checklist | AWX / Ansible |
The examples directory contains public-safe templates for common homelab patterns:
- NGINX reverse proxy
- Docker Compose apps
- Prometheus scrape config
- Pi-hole local DNS records
- Cloudflare Tunnel config shape
- Environment file placeholders
These examples are teaching templates, not production config dumps. Replace placeholder values only in private config, and never commit real credentials.
The sanitized high-level architecture is documented here:
At a high level, the flow is:
Internet
-> Cloudflare Tunnel / VPN
-> pfSense
-> LAN / VLANs
-> Pi-hole DNS
-> Proxmox workloads
-> Storage, monitoring, media, local AI, personal apps, and automation
All names and networks in public examples use sanitized values such as home.example.com and 10.10.0.0/24.
| Diagram | Use It To Understand |
|---|---|
| Homelab Overview | The full sanitized architecture |
| DNS Flow | pfSense DHCP, Pi-hole, local records, and upstream DNS |
| Backup Flow | VM backups, app data, ZFS snapshots, and restore testing |
| Reverse Proxy Flow | Internal HTTPS and selected public access |
| Local AI Flow | Open WebUI, local API endpoint, llama.cpp, model storage, and GPU runtime |
| Monitoring Flow | Exporters, Prometheus, Loki, Grafana, alerts, and review loops |
| This Repo Is | This Repo Is Not |
|---|---|
| A public learning resource for KeepItTechie readers | A dump of private production configs |
| A sanitized architecture guide | A live DNS zone or firewall export |
| A guide to safe homelab patterns | A credential store |
| A rebuild and documentation aid | A full backup of the lab |
| A place for safe examples | A place for real secrets, keys, or private data |
Short version: this repo teaches the lab design. It is not a live backup, inventory export, credential store, or screenshot dump.
- Tour the current setup.
- Use Replication Quickstart to copy the architecture pattern safely.
- Use Build Your Own Homelab if you want to build something similar in stages.
- Open the diagram index to see the flows visually.
- Browse the service catalog or service matrix.
- Read the service README for the part of the lab you want to understand.
- Compare the docs with the sanitized examples.
- Check Security Notes before adapting any pattern in a public repo.
For a beginner-friendly walkthrough, use the Viewer Guide. For deeper navigation, use the Documentation Index and Glossary.
Use these pages when you want a guided path through the repo instead of browsing every service one by one:
- Homelab Guides
- Learning Paths
- Replication Quickstart
- Full Homelab Tour Guide
- Homelab DNS and Pi-hole Guide
- Proxmox VM Layout Guide
- Homelab Backups and Restore Testing Guide
- Homelab Monitoring with Grafana and Prometheus Guide
- Homelab Reverse Proxy and Internal HTTPS Guide
- Local AI on Linux Guide
- Content Map
Core guide topics include the full homelab tour, pfSense, Pi-hole, Proxmox, Proxmox Backup Server, Synology vs ZFS, reverse proxying, Cloudflare Tunnel, Grafana monitoring, local AI, dashboards, AWX, and local-first personal apps.
This repo should never contain:
- Real passwords or recovery codes
- API keys, service account credentials, or tunnel credentials
- SSH private keys, VPN keys, or backup encryption keys
- Private certificates or certificate authority keys
- Full pfSense, switch, NAS, or app exports with secrets
- Real public IP addresses
- Raw
.envfiles - Financial data, job application data, private messages, or personal records
Use .env.example, sanitized YAML, diagrams, and Markdown explanations instead. A good public doc should explain the pattern without leaking the real system.
Screenshots need the same review as config snippets. See the Screenshot Policy before adding images.
Pull requests run lightweight documentation checks for Markdown links, diagram structure, public-safety patterns, and whitespace. The same checks can be run locally from scripts/README.md.
| Path | Purpose |
|---|---|
docs/ |
Main reader-facing documentation |
services/ |
Per-service breakdowns |
diagrams/ |
Public-safe architecture diagrams and placeholders |
assets/ |
Placeholder area for reviewed public-safe visual assets |
examples/ |
Sanitized configuration examples and templates |
inventory/sanitized/ |
Safe example inventory |
inventory/private.example/ |
Pattern for private inventory that should stay untracked |
scripts/ |
Lightweight documentation quality and public-safety checks |
templates/ |
Reusable documentation templates |
This is mainly a public documentation repo for the KeepItTechie homelab, but typo fixes, diagram improvements, sanitized examples, and beginner-friendly documentation improvements are welcome.
- Contributing guide
- Pull request template
- Issue templates
- GitHub repo settings guide
- Release checklist
This homelab documentation is licensed under the Creative Commons Attribution 4.0 International License.
You are free to share and adapt the material as long as you give appropriate credit to Joshua Lacy / KeepItTechie.