diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 719769a..44fa454 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -67,4 +67,4 @@ Use the issue templates for documentation improvements, safety reviews, and sani ## Tone -Keep the writing practical and approachable. This repo should feel like a companion to a KeepItTechie video: useful, clear, and grounded in real homelab learning without exposing private operational details. +Keep the writing practical and approachable. This repo should feel like a useful KeepItTechie homelab guide: clear, grounded in real learning, and careful about private operational details. diff --git a/README.md b/README.md index b5a2a44..8b90c54 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ ![License](https://img.shields.io/badge/license-CC%20BY%204.0-green) ![Homelab](https://img.shields.io/badge/homelab-linux%20%7C%20self--hosted-lightgrey) -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 viewers can learn from running real Linux and open source services at home. +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. @@ -38,7 +38,7 @@ The lab is easier to understand when it is broken into roles instead of treated | Storage and backups | [Storage and Monitoring](docs/storage-monitoring.md), [Storage and Backups](docs/storage-and-backups.md) | [Synology](services/synology/README.md), [ZFS Storage](services/zfs-storage/README.md), [Proxmox Backup Server](services/proxmox-backup-server/README.md) | | Observability | [Storage and Monitoring](docs/storage-monitoring.md), [Service Matrix](docs/service-matrix.md) | [Monitoring](services/monitoring/README.md) | | Media | [Apps and AI](docs/apps-and-ai.md), [Service Matrix](docs/service-matrix.md) | [Media Stack](services/media-stack/README.md) | -| Local AI | [Apps and AI](docs/apps-and-ai.md), [Content Map](docs/content-map.md) | [Local AI](services/local-ai/README.md) | +| Local AI | [Apps and AI](docs/apps-and-ai.md), [Learning Paths](docs/learning-paths.md) | [Local AI](services/local-ai/README.md) | | Documentation and dashboard | [Apps and AI](docs/apps-and-ai.md), [Diagrams](diagrams/README.md) | [Wiki.js](services/wiki/README.md), [Glance Dashboard](services/glance/README.md) | | Personal apps | [Apps and AI](docs/apps-and-ai.md), [Security Notes](docs/security-notes.md) | [FinanceHQ](services/financehq/README.md), [CareerFill](services/careerfill/README.md) | | Automation | [Apps and AI](docs/apps-and-ai.md), [Maintenance Checklist](docs/maintenance-checklist.md) | [AWX / Ansible](services/automation-awx/README.md) | @@ -94,7 +94,7 @@ All names and networks in public examples use sanitized values such as `home.exa |---|---| | A public learning resource for KeepItTechie viewers | A dump of private production configs | | A sanitized architecture guide | A live DNS zone or firewall export | -| A companion to homelab videos | A credential store | +| 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 | @@ -112,22 +112,22 @@ Short version: this repo teaches the lab design. It is not a live backup, invent For a beginner-friendly walkthrough, use the [Viewer Guide](docs/viewer-guide.md). For deeper navigation, use the [Documentation Index](docs/docs-index.md) and [Glossary](docs/glossary.md). -## YouTube Companion Series +## Guides and Learning Paths -This repo is designed to support KeepItTechie videos. The companion plan is here: +Use these pages when you want a guided path through the repo instead of browsing every service one by one: -- [Episode Companion Pages](docs/episodes/README.md) -- [Full Homelab Tour Companion](docs/episodes/full-homelab-tour.md) -- [Homelab DNS and Pi-hole Companion](docs/episodes/dns-pihole.md) -- [Proxmox VM Layout Companion](docs/episodes/proxmox-vm-layout.md) -- [Homelab Backups and Restore Testing Companion](docs/episodes/backups-restore.md) -- [Homelab Monitoring with Grafana and Prometheus Companion](docs/episodes/monitoring-grafana.md) -- [Homelab Reverse Proxy and Internal HTTPS Companion](docs/episodes/reverse-proxy.md) -- [Local AI on Linux Companion](docs/episodes/local-ai.md) -- [YouTube Companion Series](docs/youtube-series.md) +- [Homelab Guides](docs/guides/README.md) +- [Learning Paths](docs/learning-paths.md) +- [Full Homelab Tour Guide](docs/guides/full-homelab-tour.md) +- [Homelab DNS and Pi-hole Guide](docs/guides/dns-pihole.md) +- [Proxmox VM Layout Guide](docs/guides/proxmox-vm-layout.md) +- [Homelab Backups and Restore Testing Guide](docs/guides/backups-restore.md) +- [Homelab Monitoring with Grafana and Prometheus Guide](docs/guides/monitoring-grafana.md) +- [Homelab Reverse Proxy and Internal HTTPS Guide](docs/guides/reverse-proxy.md) +- [Local AI on Linux Guide](docs/guides/local-ai.md) - [Content Map](docs/content-map.md) -Planned 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. +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. ## Security First diff --git a/assets/README.md b/assets/README.md index e6262b2..2f8959f 100644 --- a/assets/README.md +++ b/assets/README.md @@ -10,7 +10,7 @@ No real screenshots or dashboard images are included yet. Any future image added |---|---| | `assets/diagrams/` | Exported public-safe diagrams | | `assets/screenshots/` | Reviewed screenshots or demo screenshots | -| `assets/thumbnails/` | YouTube, GitHub, or social preview images | +| `assets/thumbnails/` | GitHub or social preview images | | `assets/mockups/` | Recreated UI mockups and fake-data visuals | ## Rules Before Adding Images diff --git a/docs/apps-and-ai.md b/docs/apps-and-ai.md index 0b08fbd..67584a0 100644 --- a/docs/apps-and-ai.md +++ b/docs/apps-and-ai.md @@ -4,13 +4,13 @@ This page is the beginner-friendly entry point for the application, media, dashb These services sit on top of the core infrastructure, storage, backups, monitoring, and reverse proxy layers. They are the part viewers are most likely to recognize from daily use, but they also carry the most private data. -For a visual reference, see the [local AI flow diagram](../diagrams/local-ai-flow.md). For the episode companion, see [Local AI on Linux](episodes/local-ai.md). For unfamiliar app, endpoint, and public-safe documentation terms, use the [Glossary](glossary.md). +For a visual reference, see the [local AI flow diagram](../diagrams/local-ai-flow.md). For the guide, see [Local AI on Linux](guides/local-ai.md). For unfamiliar app, endpoint, and public-safe documentation terms, use the [Glossary](glossary.md). ## Recommended Reading Order | Step | Topic | Link | Why Start Here | |---|---|---|---| -| 1 | Local AI | [Local AI Stack](../services/local-ai/README.md), [Local AI Companion](episodes/local-ai.md) | Learn the GPU, endpoint, model, and Open WebUI pattern | +| 1 | Local AI | [Local AI Stack](../services/local-ai/README.md), [Local AI Guide](guides/local-ai.md) | Learn the GPU, endpoint, model, and Open WebUI pattern | | 2 | Dashboard | [Glance / Homepage Dashboard](../services/glance/README.md) | See how services are grouped for daily use | | 3 | Documentation | [Wiki.js](../services/wiki/README.md) | Learn public/private documentation boundaries | | 4 | Media | [Media Stack](../services/media-stack/README.md) | Understand storage-heavy multi-app workflows | @@ -65,7 +65,7 @@ Do not document: - [Core Infrastructure](core-infrastructure.md) - [Storage and Monitoring](storage-monitoring.md) -- [Local AI on Linux Companion](episodes/local-ai.md) +- [Local AI on Linux Guide](guides/local-ai.md) - [Glossary](glossary.md) - [How To Read Service Pages](how-to-read-service-pages.md) - [Public-Safe Diagrams](../diagrams/README.md) diff --git a/docs/build-your-own.md b/docs/build-your-own.md index 5ea7b3d..1b80a47 100644 --- a/docs/build-your-own.md +++ b/docs/build-your-own.md @@ -72,7 +72,7 @@ Focus on: Related docs: -- [Homelab DNS and Pi-hole Companion](episodes/dns-pihole.md) +- [Homelab DNS and Pi-hole Guide](guides/dns-pihole.md) - [Pi-hole](../services/pihole/README.md) - [Pi-hole DNS Example](../examples/pihole/README.md) @@ -92,7 +92,7 @@ Service identity is the name users remember, such as `proxy.home.example.com`. M Related docs: -- [Proxmox VM Layout Companion](episodes/proxmox-vm-layout.md) +- [Proxmox VM Layout Guide](guides/proxmox-vm-layout.md) - [Proxmox](../services/proxmox/README.md) - [Core Infrastructure](core-infrastructure.md) @@ -133,7 +133,7 @@ A backup is only useful when the restore path works. Keep a short restore log so Related docs: -- [Homelab Backups and Restore Testing Companion](episodes/backups-restore.md) +- [Homelab Backups and Restore Testing Guide](guides/backups-restore.md) - [Storage and Backups](storage-and-backups.md) - [Proxmox Backup Server](../services/proxmox-backup-server/README.md) - [Backup Flow Diagram](../diagrams/backup-flow.md) @@ -155,7 +155,7 @@ Monitoring is useful when it helps answer: what changed, what is unhealthy, and Related docs: -- [Homelab Monitoring with Grafana and Prometheus Companion](episodes/monitoring-grafana.md) +- [Homelab Monitoring with Grafana and Prometheus Guide](guides/monitoring-grafana.md) - [Monitoring](../services/monitoring/README.md) - [Monitoring Flow Diagram](../diagrams/monitoring-flow.md) @@ -175,7 +175,7 @@ Not every dashboard should be public. Hypervisors, backup systems, admin dashboa Related docs: -- [Homelab Reverse Proxy and Internal HTTPS Companion](episodes/reverse-proxy.md) +- [Homelab Reverse Proxy and Internal HTTPS Guide](guides/reverse-proxy.md) - [Reverse Proxy](../services/reverse-proxy/README.md) - [Cloudflare Tunnel](../services/cloudflare-tunnel/README.md) - [NGINX Example](../examples/nginx/README.md) @@ -221,7 +221,7 @@ A GPU helps with many workloads, but it is not required to learn the architectur Related docs: -- [Local AI on Linux Companion](episodes/local-ai.md) +- [Local AI on Linux Guide](guides/local-ai.md) - [Local AI](../services/local-ai/README.md) - [Local AI Flow Diagram](../diagrams/local-ai-flow.md) @@ -266,16 +266,16 @@ Related docs: | 4 | Virtualization | [Proxmox](../services/proxmox/README.md), [Core Infrastructure](core-infrastructure.md) | | 5 | Storage | [Storage and Monitoring](storage-monitoring.md), [Synology NAS](../services/synology/README.md), [ZFS Storage](../services/zfs-storage/README.md) | | 6 | Backups | [Storage and Backups](storage-and-backups.md), [Backup Flow Diagram](../diagrams/backup-flow.md) | -| 7 | Monitoring | [Monitoring](../services/monitoring/README.md), [Monitoring Companion](episodes/monitoring-grafana.md), [Monitoring Flow Diagram](../diagrams/monitoring-flow.md) | -| 8 | Reverse proxying | [Reverse Proxy](../services/reverse-proxy/README.md), [Reverse Proxy Companion](episodes/reverse-proxy.md), [NGINX Example](../examples/nginx/README.md) | +| 7 | Monitoring | [Monitoring](../services/monitoring/README.md), [Monitoring Guide](guides/monitoring-grafana.md), [Monitoring Flow Diagram](../diagrams/monitoring-flow.md) | +| 8 | Reverse proxying | [Reverse Proxy](../services/reverse-proxy/README.md), [Reverse Proxy Guide](guides/reverse-proxy.md), [NGINX Example](../examples/nginx/README.md) | | 9 | Self-hosted apps | [Apps and AI](apps-and-ai.md), [Service Catalog](service-catalog.md) | -| 10 | Local AI | [Local AI](../services/local-ai/README.md), [Local AI Companion](episodes/local-ai.md), [Local AI Flow Diagram](../diagrams/local-ai-flow.md) | +| 10 | Local AI | [Local AI](../services/local-ai/README.md), [Local AI Guide](guides/local-ai.md), [Local AI Flow Diagram](../diagrams/local-ai-flow.md) | | 11 | Automation | [AWX / Ansible Automation](../services/automation-awx/README.md), [Sanitized Examples](../examples/README.md) | ## Related Docs - [Current Setup](current-setup.md) -- [Full Homelab Tour Companion](episodes/full-homelab-tour.md) +- [Full Homelab Tour Guide](guides/full-homelab-tour.md) - [Viewer Guide](viewer-guide.md) - [Documentation Index](docs-index.md) - [Glossary](glossary.md) diff --git a/docs/content-map.md b/docs/content-map.md index 6665fcf..a04e615 100644 --- a/docs/content-map.md +++ b/docs/content-map.md @@ -1,86 +1,47 @@ -# KeepItTechie Content Map +# Content Map -This repo can support a full KeepItTechie homelab series. Each topic should connect a real lab service to a practical lesson viewers can reuse. +This page maps the repo by learning topic. It is meant to help readers connect a homelab area to the docs, diagrams, guides, and sanitized examples that explain it. -For the more detailed episode-by-episode plan, see [YouTube Companion Series](youtube-series.md). +For guided reading paths, see [Learning Paths](learning-paths.md). -## Series Structure +## Topic Map -| Episode | Topic | Viewer Takeaway | +| Topic | Reader Takeaway | Start Here | |---|---|---| -| 1 | Full homelab overview | How the pieces fit together without getting lost in tools | -| 2 | pfSense firewall design | Basic routing, DHCP, firewall rules, and safe exposure | -| 3 | Pi-hole DNS pair | Local DNS, redundancy, ad blocking, and service names | -| 4 | Proxmox virtualization | Why VMs make a homelab easier to test and rebuild | -| 5 | Proxmox Backup Server | Backups, retention, and restore tests that actually matter | -| 6 | Synology plus ZFS storage | Appliance NAS vs Linux storage server tradeoffs | -| 7 | NGINX reverse proxy | Clean internal URLs and service routing | -| 8 | Cloudflare Tunnel | Publishing selected services without opening everything | -| 9 | Monitoring stack | Grafana, Prometheus, logs, exporters, and uptime checks | -| 10 | Media stack | Plex, Servarr, Tautulli, and Tdarr as a real app ecosystem | -| 11 | Local AI | Running AI locally with a GPU server and Open WebUI | -| 12 | Wiki.js | Building a documentation habit for the lab | -| 13 | Glance dashboard | Creating a simple control surface for daily use | -| 14 | FinanceHQ | Local-first personal apps and privacy-minded design | -| 15 | CareerFill | Automation for job search workflows | -| 16 | AWX / Ansible | Turning repeatable admin work into automation | - -## Episode Template - -```text -Problem: -What pain point does this solve? - -Where it fits: -What depends on it, and what does it depend on? - -Build: -What are the main install or configuration steps? - -Security: -What should stay private? - -Demo: -What does success look like? - -Failure mode: -What breaks when this service is down? - -Takeaway: -What can viewers reuse in their own lab? -``` - -## Good Demo Angles - -| Service | Demo Idea | -|---|---| -| pfSense | Show rule thinking with sanitized networks | -| Pi-hole | Add a local DNS record and resolve a service name | -| Proxmox | Clone or restore a test VM | -| PBS | Restore a VM into an isolated test network | -| Reverse proxy | Add a new internal service identity | -| Monitoring | Build a simple dashboard from node metrics | -| Loki / Promtail | Trace a service issue through logs | -| Media stack | Explain how each app has a different role | -| Local AI | Send a request to a local OpenAI-compatible endpoint | -| Wiki.js | Convert a private runbook idea into a public-safe doc | -| Glance | Build a dashboard section for core services | -| AWX | Run a safe read-only homelab check playbook | - -## Public Safety For Videos - -- Blur real public domains, real public IPs, tokens, and account identifiers. -- Prefer recreated examples over live admin screens. -- Avoid showing full firewall exports or full DNS record lists. -- Use `home.example.com` and `10.10.0.0/24` in slides and diagrams. -- Keep private Wiki.js admin pages out of public screen recordings. - -## Repo Tie-In - -Each video can point viewers to: - -- The service README for the architecture. -- The sanitized inventory for naming patterns. -- The diagram notes for topology. -- The security notes for what not to publish. -- The [service matrix](service-matrix.md) for access and backup priority. +| Full homelab overview | How the major pieces fit together without getting lost in tools | [Current Setup](current-setup.md), [Full Homelab Tour Guide](guides/full-homelab-tour.md) | +| pfSense firewall design | Basic routing, DHCP, firewall policy, and safe exposure boundaries | [Network Design](network.md), [pfSense](../services/pfsense/README.md) | +| Pi-hole DNS pair | Local DNS, redundancy, filtering, and service names | [Homelab DNS and Pi-hole](guides/dns-pihole.md), [Pi-hole](../services/pihole/README.md) | +| Proxmox virtualization | Why VMs make a homelab easier to test, group, and rebuild | [Proxmox VM Layout](guides/proxmox-vm-layout.md), [Proxmox](../services/proxmox/README.md) | +| Proxmox Backup Server | Backups, retention concepts, and restore tests that actually matter | [Backups and Restore Testing](guides/backups-restore.md), [PBS](../services/proxmox-backup-server/README.md) | +| Synology and ZFS storage | Appliance NAS workflows and Linux storage learning | [Storage and Backups](storage-and-backups.md), [Storage and Monitoring](storage-monitoring.md) | +| NGINX reverse proxy | Clean internal URLs, TLS concepts, and routing to backend apps | [Reverse Proxy Guide](guides/reverse-proxy.md), [Reverse Proxy](../services/reverse-proxy/README.md) | +| Cloudflare Tunnel | Selected public access without publishing every internal service | [Cloudflare Tunnel](../services/cloudflare-tunnel/README.md), [Security Notes](security-notes.md) | +| Monitoring stack | Grafana, Prometheus, logs, exporters, and uptime checks | [Monitoring Guide](guides/monitoring-grafana.md), [Monitoring](../services/monitoring/README.md) | +| Media stack | Plex, Servarr-style automation, Tautulli, and Tdarr as a multi-app workflow | [Media Stack](../services/media-stack/README.md), [Apps and AI](apps-and-ai.md) | +| Local AI | Running AI locally with a GPU server concept, Open WebUI, and private endpoints | [Local AI Guide](guides/local-ai.md), [Local AI Stack](../services/local-ai/README.md) | +| Wiki.js | Building a documentation habit while keeping private notes private | [Wiki.js](../services/wiki/README.md), [Docs Index](docs-index.md) | +| Glance dashboard | Creating a simple daily control surface without exposing admin links | [Glance](../services/glance/README.md), [Apps and AI](apps-and-ai.md) | +| FinanceHQ | Local-first personal app patterns with demo data only | [FinanceHQ](../services/financehq/README.md), [Security Notes](security-notes.md) | +| CareerFill | Career workflow app patterns without publishing job or resume data | [CareerFill](../services/careerfill/README.md), [Security Notes](security-notes.md) | +| AWX / Ansible | Turning repeatable admin work into safe automation patterns | [AWX / Ansible](../services/automation-awx/README.md), [Sanitized Inventory](../inventory/sanitized/hosts.example.yml) | + +## How to Use This Map + +- Start with the topic that matches the current question. +- Open the guide first if one exists. +- Use service docs to understand purpose, placement, network behavior, backups, and security notes. +- Use diagrams to see the flow visually. +- Use sanitized examples only as templates, not production config. + +## Public-Safe Boundaries + +This map intentionally avoids exact host IPs, live internal domains, raw exports, credentials, screenshots, serial numbers, MAC addresses, financial data, and career data. + +## Related Docs + +- [Learning Paths](learning-paths.md) +- [Current Setup](current-setup.md) +- [Build Your Own Homelab](build-your-own.md) +- [Service Catalog](service-catalog.md) +- [Service Matrix](service-matrix.md) +- [Sanitized Examples](../examples/README.md) diff --git a/docs/core-infrastructure.md b/docs/core-infrastructure.md index 0eec6cc..91a6a43 100644 --- a/docs/core-infrastructure.md +++ b/docs/core-infrastructure.md @@ -12,9 +12,9 @@ For visual references, start with the [homelab overview diagram](../diagrams/hom |---|---|---| | 1 | [pfSense](../services/pfsense/README.md) | Understand routing, firewall policy, DHCP, and network boundaries | | 2 | [Pi-hole](../services/pihole/README.md) | Understand internal DNS, local service names, and DNS filtering | -| 3 | [Proxmox](../services/proxmox/README.md) and [Proxmox VM Layout Companion](episodes/proxmox-vm-layout.md) | Understand where the VMs and containers run | +| 3 | [Proxmox](../services/proxmox/README.md) and [Proxmox VM Layout Guide](guides/proxmox-vm-layout.md) | Understand where the VMs and containers run | | 4 | [Proxmox Backup Server](../services/proxmox-backup-server/README.md) | Understand how VM recovery is planned | -| 5 | [Reverse Proxy](../services/reverse-proxy/README.md) and [Reverse Proxy Companion](episodes/reverse-proxy.md) | Understand internal HTTPS and service identities | +| 5 | [Reverse Proxy](../services/reverse-proxy/README.md) and [Reverse Proxy Guide](guides/reverse-proxy.md) | Understand internal HTTPS and service identities | | 6 | [Cloudflare Tunnel](../services/cloudflare-tunnel/README.md) | Understand selected public access and why most admin tools stay private | ## Core Stack Summary @@ -73,8 +73,8 @@ Do not document: - [Storage and Monitoring](storage-monitoring.md) - [Apps and AI](apps-and-ai.md) -- [Homelab Reverse Proxy and Internal HTTPS Companion](episodes/reverse-proxy.md) -- [Proxmox VM Layout Companion](episodes/proxmox-vm-layout.md) +- [Homelab Reverse Proxy and Internal HTTPS Guide](guides/reverse-proxy.md) +- [Proxmox VM Layout Guide](guides/proxmox-vm-layout.md) - [Glossary](glossary.md) - [How To Read Service Pages](how-to-read-service-pages.md) - [Public-Safe Diagrams](../diagrams/README.md) diff --git a/docs/current-setup.md b/docs/current-setup.md index 6e45cd9..05d5f1c 100644 --- a/docs/current-setup.md +++ b/docs/current-setup.md @@ -20,7 +20,7 @@ This section teaches how routing, firewall policy, DHCP, DNS, and segmentation w Related docs: -- [Homelab DNS and Pi-hole Companion](episodes/dns-pihole.md) +- [Homelab DNS and Pi-hole Guide](guides/dns-pihole.md) - [Network Design](network.md) - [Core Infrastructure](core-infrastructure.md) - [DNS Flow Diagram](../diagrams/dns-flow.md) @@ -37,7 +37,7 @@ This is where viewers can see why virtualization is useful in a homelab: isolati Related docs: -- [Proxmox VM Layout Companion](episodes/proxmox-vm-layout.md) +- [Proxmox VM Layout Guide](guides/proxmox-vm-layout.md) - [Proxmox](../services/proxmox/README.md) - [Core Infrastructure](core-infrastructure.md) @@ -66,7 +66,7 @@ Viewers can learn how VM backups, app-aware backups, NAS targets, ZFS snapshots, Related docs: -- [Homelab Backups and Restore Testing Companion](episodes/backups-restore.md) +- [Homelab Backups and Restore Testing Guide](guides/backups-restore.md) - [Proxmox Backup Server](../services/proxmox-backup-server/README.md) - [Backup Flow Diagram](../diagrams/backup-flow.md) - [Storage and Backups](storage-and-backups.md) @@ -81,7 +81,7 @@ Viewers can learn the difference between metrics, logs, dashboards, and service Related docs: -- [Homelab Monitoring with Grafana and Prometheus Companion](episodes/monitoring-grafana.md) +- [Homelab Monitoring with Grafana and Prometheus Guide](guides/monitoring-grafana.md) - [Monitoring](../services/monitoring/README.md) - [Monitoring Flow Diagram](../diagrams/monitoring-flow.md) @@ -95,7 +95,7 @@ Viewers can learn the difference between internal reverse proxy access, VPN-styl Related docs: -- [Homelab Reverse Proxy and Internal HTTPS Companion](episodes/reverse-proxy.md) +- [Homelab Reverse Proxy and Internal HTTPS Guide](guides/reverse-proxy.md) - [Reverse Proxy](../services/reverse-proxy/README.md) - [Cloudflare Tunnel](../services/cloudflare-tunnel/README.md) - [Reverse Proxy Flow Diagram](../diagrams/reverse-proxy-flow.md) @@ -124,7 +124,7 @@ Viewers can learn how a local AI service can support private experimentation wit Related docs: -- [Local AI on Linux Companion](episodes/local-ai.md) +- [Local AI on Linux Guide](guides/local-ai.md) - [Local AI](../services/local-ai/README.md) - [Local AI Flow Diagram](../diagrams/local-ai-flow.md) @@ -185,7 +185,7 @@ Related docs: ## Where to Go Next 1. [Viewer Guide](viewer-guide.md) -2. [Full Homelab Tour Companion](episodes/full-homelab-tour.md) +2. [Full Homelab Tour Guide](guides/full-homelab-tour.md) 3. [Build Your Own Homelab](build-your-own.md) 4. [Glossary](glossary.md) 5. [Hardware](hardware.md) diff --git a/docs/docs-index.md b/docs/docs-index.md index 1bb3cf0..7212b2c 100644 --- a/docs/docs-index.md +++ b/docs/docs-index.md @@ -102,19 +102,24 @@ Use this page when the README is too high-level and a more complete map of the r | [Pre-Publish Review](pre-publish-review.md) | Public-safe review before publishing or merging | | [Local Quality Scripts](../scripts/README.md) | How to run documentation quality checks locally | +## Guides and Learning Paths + +| Page | Purpose | +|---|---| +| [Learning Paths](learning-paths.md) | Practical reading paths through the repo | +| [Homelab Guides](guides/README.md) | Public-safe topic guides | +| [Full Homelab Tour Guide](guides/full-homelab-tour.md) | Broad lab walkthrough | +| [Homelab DNS and Pi-hole Guide](guides/dns-pihole.md) | Local DNS, filtering, and service names | +| [Proxmox VM Layout Guide](guides/proxmox-vm-layout.md) | Virtualization and VM organization | +| [Homelab Backups and Restore Testing Guide](guides/backups-restore.md) | Backup strategy, PBS, and restore verification | +| [Homelab Monitoring with Grafana and Prometheus Guide](guides/monitoring-grafana.md) | Metrics, logs, uptime checks, and dashboards | +| [Homelab Reverse Proxy and Internal HTTPS Guide](guides/reverse-proxy.md) | Reverse proxying, TLS, and selected public access | +| [Local AI on Linux Guide](guides/local-ai.md) | Local AI services, endpoints, and privacy boundaries | +| [Content Map](content-map.md) | Repo topic map | + ## Planning and Roadmap | Page | Purpose | |---|---| | [Documentation Roadmap](roadmap.md) | Completed phases and future work | | [Maintenance Checklist](maintenance-checklist.md) | Ongoing repo maintenance checklist | -| [YouTube Companion Series](youtube-series.md) | Video topic plan tied to repo docs | -| [Episode Companion Pages](episodes/README.md) | Viewer-facing pages tied to KeepItTechie videos | -| [Full Homelab Tour Companion](episodes/full-homelab-tour.md) | First episode guide for the broad lab tour | -| [Homelab DNS and Pi-hole Companion](episodes/dns-pihole.md) | Episode guide for local DNS, filtering, and service names | -| [Proxmox VM Layout Companion](episodes/proxmox-vm-layout.md) | Episode guide for virtualization and VM organization | -| [Homelab Backups and Restore Testing Companion](episodes/backups-restore.md) | Episode guide for backup strategy, PBS, and restore verification | -| [Homelab Monitoring with Grafana and Prometheus Companion](episodes/monitoring-grafana.md) | Episode guide covering metrics, logs, uptime checks, and dashboards | -| [Homelab Reverse Proxy and Internal HTTPS Companion](episodes/reverse-proxy.md) | Episode guide covering reverse proxying, TLS, and selected public access | -| [Local AI on Linux Companion](episodes/local-ai.md) | Episode guide covering local AI services, endpoints, and privacy boundaries | -| [Content Map](content-map.md) | Repo-to-content mapping | diff --git a/docs/episodes/README.md b/docs/guides/README.md similarity index 65% rename from docs/episodes/README.md rename to docs/guides/README.md index 59d7204..6032c2e 100644 --- a/docs/episodes/README.md +++ b/docs/guides/README.md @@ -1,12 +1,12 @@ -# Episode Companion Pages +# Homelab Guides -This folder collects public-safe companion pages for KeepItTechie homelab videos. Each page gives viewers the repo links, safe demo ideas, and follow-up reading needed to continue learning after a video. +This folder collects public-safe topic guides for the KeepItTechie homelab. Each guide explains a core pattern, links to supporting docs, and shows how to study the setup without exposing private infrastructure. -These pages are not private scripts or production notes. They are viewer-facing guides that use sanitized examples and avoid live infrastructure details. +These pages are not scripts, show notes, or private runbooks. They are repo-focused learning guides that use sanitized examples and avoid live infrastructure details. -## Episode Index +## Guide Index -| Episode | Topic | Companion Page | +| Guide | Topic | Page | |---|---|---| | Full Homelab Tour | High-level lab walkthrough | [Full Homelab Tour](full-homelab-tour.md) | | Homelab DNS and Pi-hole | Local DNS, filtering, and service names | [Homelab DNS and Pi-hole](dns-pihole.md) | @@ -16,11 +16,11 @@ These pages are not private scripts or production notes. They are viewer-facing | Homelab Reverse Proxy and Internal HTTPS | Reverse proxy, TLS, and selected public access | [Homelab Reverse Proxy and Internal HTTPS](reverse-proxy.md) | | Local AI on Linux | Local AI services, endpoints, and privacy boundaries | [Local AI on Linux](local-ai.md) | -Future companion pages can cover dashboards, self-hosted apps, and automation. +Future guides can cover dashboards, self-hosted apps, and automation. ## Related Docs -- [YouTube Companion Series](../youtube-series.md) +- [Learning Paths](../learning-paths.md) - [Current Setup](../current-setup.md) - [Build Your Own Homelab](../build-your-own.md) - [Documentation Index](../docs-index.md) diff --git a/docs/episodes/backups-restore.md b/docs/guides/backups-restore.md similarity index 92% rename from docs/episodes/backups-restore.md rename to docs/guides/backups-restore.md index dd5508e..4de707e 100644 --- a/docs/episodes/backups-restore.md +++ b/docs/guides/backups-restore.md @@ -1,14 +1,14 @@ # Homelab Backups and Restore Testing -This page is a public-safe companion guide for a KeepItTechie video about homelab backups, Proxmox Backup Server, and proving backups through restore testing. +This guide explains homelab backups, Proxmox Backup Server, and proving backups through restore testing. -## Episode Goal +## Guide Goal -This episode teaches how to think about backups in a homelab and why a restore test matters more than a "backup completed" message. +This guide teaches how to think about backups in a homelab and why a restore test matters more than a "backup completed" message. The focus is practical: protect important services, keep backup targets separate from the systems they protect, and document restore evidence without publishing private infrastructure details. -## What Viewers Will Learn +## What Readers Will Learn - Why backups should be planned before adding more services. - Why snapshots are helpful but not enough by themselves. @@ -80,9 +80,9 @@ A simple restore test can look like this: Do not publish screenshots or command output that reveals hostnames, paths, users, file names, databases, or app data from the live lab. -## Public-Safe Demo Ideas +## Public-Safe Examples -- Show the [backup flow diagram](../../diagrams/backup-flow.md). +- Open the [backup flow diagram](../../diagrams/backup-flow.md). - Walk through a sanitized restore test evidence table. - Explain the difference between a snapshot and a backup with a simple example. - Show how a backup target should be separate from the VM host. @@ -135,20 +135,20 @@ Use a simple table to record proof that a restore path works. Keep the real deta ## Commands and Examples -These commands are safe examples that viewers can adapt in their own lab. Review command output before sharing it publicly because it can include hostnames, pool names, dataset names, and paths. +These commands are safe examples that readers can adapt in their own lab. Review command output before sharing it publicly because it can include hostnames, pool names, dataset names, and paths. ```bash # List Proxmox VMs qm list -# Check ZFS pool status in a viewer's own lab +# Check ZFS pool status in a reader's own lab zpool status -# List ZFS datasets in a viewer's own lab +# List ZFS datasets in a reader's own lab zfs list ``` -## After Watching +## Next Steps - Read the [Storage and Backups](../storage-and-backups.md) guide. - Study the [backup flow diagram](../../diagrams/backup-flow.md). diff --git a/docs/episodes/dns-pihole.md b/docs/guides/dns-pihole.md similarity index 84% rename from docs/episodes/dns-pihole.md rename to docs/guides/dns-pihole.md index f07bab5..b7c19a6 100644 --- a/docs/episodes/dns-pihole.md +++ b/docs/guides/dns-pihole.md @@ -1,14 +1,14 @@ # Homelab DNS and Pi-hole -This page is a public-safe companion guide for a KeepItTechie video about DNS, Pi-hole, and local service names in a homelab. +This guide explains how DNS, Pi-hole, and local service names fit into a homelab. -## Episode Goal +## Guide Goal -The goal of this episode is to show why DNS makes a homelab easier to use. Instead of memorizing raw addresses, viewers can use readable service names such as `grafana.home.example.com`, `proxy.home.example.com`, and `nas.home.example.com`. +This guide shows why DNS makes a homelab easier to use. Instead of memorizing raw addresses, readers can use readable service names such as `grafana.home.example.com`, `proxy.home.example.com`, and `nas.home.example.com`. For beginners, the key idea is simple: DNS is the phone book for the lab. Pi-hole can answer local names, filter unwanted domains, and forward everything else upstream. -## What Viewers Will Learn +## What Readers Will Learn - What DNS does. - Why local DNS matters in a homelab. @@ -31,7 +31,7 @@ Local DNS helps with: - Fewer hardcoded addresses in notes and bookmarks. - Clear separation between service identity and machine identity. -DNS also makes the lab easier to teach. Viewers can understand what a service does by its name before learning which VM, container, or host runs it. +DNS also makes the lab easier to explain. Readers can understand what a service does by its name before learning which VM, container, or host runs it. ## Where Pi-hole Fits @@ -66,7 +66,7 @@ Both resolvers should be documented, backed up, and kept private. Local DNS records map names to internal services. This is where service identity and machine identity become useful. -- **Service identity:** The name viewers or users type, such as `grafana.home.example.com`. +- **Service identity:** The name readers or users type, such as `grafana.home.example.com`. - **Machine identity:** The VM, container host, or physical machine that runs the workload. Keeping those separate makes services easier to move later. Public docs use sanitized examples so the pattern is visible without publishing the real DNS zone. @@ -85,15 +85,15 @@ Client joins network This keeps clients pointed at the intended DNS path. If clients are pointed at random public DNS servers, local names may fail and DNS filtering visibility becomes incomplete. -## Public-Safe Demo Ideas +## Public-Safe Examples -- Show the [DNS flow diagram](../../diagrams/dns-flow.md). -- Show the [sanitized Pi-hole CSV example](../../examples/pihole/local-dns-records.example.csv). +- Open the [DNS flow diagram](../../diagrams/dns-flow.md). +- Open the [sanitized Pi-hole CSV example](../../examples/pihole/local-dns-records.example.csv). - Explain service names such as `proxy.home.example.com`, `grafana.home.example.com`, and `nas.home.example.com`. -- Show how DNS reduces raw address memorization. -- Explain what not to publish: live records, admin screenshots, raw exports, and private domains. +- Explain how DNS reduces raw address memorization. +- Review what not to publish: live records, admin screenshots, raw exports, and private domains. -Do not show a real Pi-hole admin page unless it is sanitized or uses demo data. +Do not include a real Pi-hole admin page unless it is sanitized or uses demo data. ## Example Local DNS Records @@ -144,7 +144,7 @@ Related safe examples: - [Pi-hole example notes](../../examples/pihole/README.md) - [Sanitized local DNS CSV](../../examples/pihole/local-dns-records.example.csv) -## After Watching +## Next Steps - Read the [Pi-hole service doc](../../services/pihole/README.md). - Study the [DNS flow diagram](../../diagrams/dns-flow.md). diff --git a/docs/episodes/full-homelab-tour.md b/docs/guides/full-homelab-tour.md similarity index 69% rename from docs/episodes/full-homelab-tour.md rename to docs/guides/full-homelab-tour.md index 3eee66c..06458ae 100644 --- a/docs/episodes/full-homelab-tour.md +++ b/docs/guides/full-homelab-tour.md @@ -1,21 +1,21 @@ # Full Homelab Tour -This page is a public-safe companion guide for a KeepItTechie homelab tour video. +This guide gives a public-safe tour of the KeepItTechie homelab setup. -## Episode Goal +## Guide Goal -The goal of this episode is to introduce the major layers of the KeepItTechie homelab without turning the tour into a private inventory dump. +This guide introduces the major layers of the KeepItTechie homelab without turning the tour into a private inventory dump. -A full tour can show how the network, DNS, virtualization, storage, backups, monitoring, reverse proxy, media services, local AI, documentation, automation, and personal apps fit together. For beginners, the key takeaway is that a homelab becomes easier to understand when every service has a role. +A full repo tour shows how the network, DNS, virtualization, storage, backups, monitoring, reverse proxy, media services, local AI, documentation, automation, and personal apps fit together. For beginners, the key takeaway is that a homelab becomes easier to understand when every service has a role. -## What Viewers Will Learn +## What Readers Will Learn - Why a homelab is useful for learning Linux, networking, storage, automation, and self-hosting. - How services are grouped by role instead of treated as one giant stack. - Why DNS matters once more than a few services exist. - Why backups should come before adding too much complexity. - Why not every service should be exposed publicly. -- How diagrams and sanitized examples help viewers learn safely. +- How diagrams and sanitized examples help readers learn safely. - How this repo separates public teaching docs from private config. ## Lab Areas Covered @@ -35,20 +35,20 @@ A full tour can show how the network, DNS, virtualization, storage, backups, mon | Documentation | Keeps public teaching docs separate from private runbooks | [Wiki.js](../../services/wiki/README.md), [Documentation Index](../docs-index.md) | | Automation | Uses AWX and Ansible concepts to make admin tasks repeatable | [AWX / Ansible](../../services/automation-awx/README.md) | -## Suggested Video Flow +## Suggested Reading Flow -1. A tour video can start with what this repo is and is not: a public-safe learning map, not a private config dump. -2. Viewers can follow the high-level diagram to see the whole lab before opening individual service docs. -3. The network and DNS section can explain pfSense, Pi-hole, service names, and why internal DNS matters. -4. The virtualization section can show how Proxmox groups workloads by role. -5. The storage and backups section can explain NAS storage, ZFS learning, Proxmox Backup Server, and restore testing. -6. The monitoring section can explain Grafana, Prometheus, exporters, Loki, logs, and service checks. -7. The apps and media section can show how user-facing apps depend on storage, DNS, proxying, and backups. -8. The local AI section can explain Open WebUI, a local OpenAI-compatible endpoint, and why AI endpoints stay protected. -9. The automation and documentation section can connect AWX, Ansible, Wiki.js, and this repo. -10. The close can point viewers to the build-your-own path so they can start small instead of copying the whole lab. +1. Start with what this repo is and is not: a public-safe learning map, not a private config dump. +2. Follow the high-level diagram to see the whole lab before opening individual service docs. +3. Read the network and DNS sections to understand pfSense, Pi-hole, service names, and why internal DNS matters. +4. Use the virtualization section to see how Proxmox groups workloads by role. +5. Study storage and backups to connect NAS storage, ZFS learning, Proxmox Backup Server, and restore testing. +6. Review monitoring to understand Grafana, Prometheus, exporters, Loki, logs, and service checks. +7. Move into apps and media to see how user-facing apps depend on storage, DNS, proxying, and backups. +8. Read the local AI section to understand Open WebUI, a local OpenAI-compatible endpoint, and why AI endpoints stay protected. +9. Connect automation and documentation through AWX, Ansible, Wiki.js, and this repo. +10. Continue with the build-your-own path to start small instead of copying the whole lab. -## Repo Files to Follow Along +## Repo Files to Start With - [README](../../README.md) - [Current Setup](../current-setup.md) @@ -60,15 +60,15 @@ A full tour can show how the network, DNS, virtualization, storage, backups, mon - [Diagrams](../../diagrams/README.md) - [Sanitized Examples](../../examples/README.md) -## Public-Safe Demo Ideas +## Public-Safe Examples - Walk through the Mermaid homelab overview diagram. - Open the sanitized DNS flow and explain how service names replace raw addresses. -- Use the service catalog to show services grouped by role. +- Use the service catalog to see services grouped by role. - Open the sanitized NGINX example and explain the reverse proxy pattern. - Open the Docker Compose template and point out placeholder values. -- Show how to read a service README: purpose, placement, network, backup, and security notes. -- Show examples of what not to publish, such as raw firewall exports, private dashboards, and live config. +- Review how to read a service README: purpose, placement, network, backup, and security notes. +- Review examples of what not to publish, such as raw firewall exports, private dashboards, and live config. Avoid live dashboards unless the view is sanitized or uses fake demo data. @@ -88,7 +88,7 @@ Avoid live dashboards unless the view is sanitized or uses fake demo data. ## Commands and Examples -Viewers can clone the public repo and run the lightweight docs checks locally: +Readers can clone the public repo and run the lightweight docs checks locally: ```bash git clone https://github.com/keepittechie/keepittechie-homelab.git @@ -101,7 +101,7 @@ python3 scripts/public_safety_scan.py These commands check documentation links, diagram structure, and obvious public-safety issues. They do not replace manual review. -## After Watching +## Next Steps - Read the [Current Setup](../current-setup.md) page. - Follow the [Build Your Own Homelab](../build-your-own.md) learning path. diff --git a/docs/episodes/local-ai.md b/docs/guides/local-ai.md similarity index 87% rename from docs/episodes/local-ai.md rename to docs/guides/local-ai.md index c034f7c..f13f175 100644 --- a/docs/episodes/local-ai.md +++ b/docs/guides/local-ai.md @@ -1,14 +1,14 @@ # Local AI on Linux -This page is a public-safe companion guide for a KeepItTechie video about running local AI services on Linux in a homelab. +This guide explains running local AI services on Linux in a homelab. -## Episode Goal +## Guide Goal -This episode introduces local AI as another self-hosted service layer in the homelab. It shows how local AI can support learning, experimentation, privacy, and Linux workflows without depending entirely on cloud tools. +This guide introduces local AI as another self-hosted service layer in the homelab. It shows how local AI can support learning, experimentation, privacy, and Linux workflows without depending entirely on cloud tools. The goal is practical: understand the moving parts, protect the endpoint, and use fake or demo data when explaining the stack publicly. -## What Viewers Will Learn +## What Readers Will Learn - What local AI means. - Why Linux is a strong platform for local AI. @@ -22,7 +22,7 @@ The goal is practical: understand the moving parts, protect the endpoint, and us Local AI gives the lab more control over where prompts and data go. It is also a good learning path for Linux, GPUs, APIs, automation, and self-hosted workflows. -Running AI locally can help viewers experiment without depending on one cloud service for every request. That does not mean local AI is automatically secure. The surrounding apps, logs, uploaded files, and integrations still need careful handling. +Running AI locally can help readers experiment without depending on one cloud service for every request. That does not mean local AI is automatically secure. The surrounding apps, logs, uploaded files, and integrations still need careful handling. Hardware limits matter too. GPU memory, CPU speed, RAM, disk space, and model size all affect the experience. @@ -80,7 +80,7 @@ Local endpoints should be private, authenticated, or tightly controlled. Never p Models can take a lot of disk space. Some models require more GPU memory than others, and quantized models can make smaller systems more useful. -Viewers do not need the biggest GPU to learn the architecture. Start with a simple model or web UI, then expand when the use case is clear. +Readers do not need the biggest GPU to learn the architecture. Start with a simple model or web UI, then expand when the use case is clear. Document model choices safely: @@ -104,16 +104,16 @@ Watch these areas closely: Treat local AI like any other powerful internal service: private by default, monitored, backed up where needed, and documented without exposing private data. -## Public-Safe Demo Ideas +## Public-Safe Examples -- Show the [local AI flow diagram](../../diagrams/local-ai-flow.md). +- Open the [local AI flow diagram](../../diagrams/local-ai-flow.md). - Use a fake prompt with no personal or operational data. -- Show a sanitized endpoint example such as `https://ai.home.example.com/v1`. +- Use a sanitized endpoint example such as `https://ai.home.example.com/v1`. - Explain Open WebUI conceptually without private chat history. - Show how an app might call a local OpenAI-compatible endpoint. -- Show what should not be published. +- Review what should not be published. -Do not show live chat logs, private prompts, uploaded documents, private model directories, or private workflow data. +Do not include live chat logs, private prompts, uploaded documents, private model directories, or private workflow data. ## Example Local AI Flow @@ -163,20 +163,20 @@ Do not show live chat logs, private prompts, uploaded documents, private model d ## Commands and Examples -These commands are safe examples that viewers can adapt in their own lab. Review command output before sharing it publicly because it can include hostnames, usernames, paths, GPU details, and running processes. +These commands are safe examples that readers can adapt in their own lab. Review command output before sharing it publicly because it can include hostnames, usernames, paths, GPU details, and running processes. ```bash # Example: check a sanitized local AI endpoint curl -I https://ai.home.example.com -# Example: inspect GPU usage in a viewer's own lab +# Example: inspect GPU usage in a reader's own lab nvidia-smi # Example: run the repo safety scan before sharing docs python3 scripts/public_safety_scan.py ``` -## After Watching +## Next Steps - Read the [Local AI Stack](../../services/local-ai/README.md) service doc. - Study the [local AI flow diagram](../../diagrams/local-ai-flow.md). diff --git a/docs/episodes/monitoring-grafana.md b/docs/guides/monitoring-grafana.md similarity index 91% rename from docs/episodes/monitoring-grafana.md rename to docs/guides/monitoring-grafana.md index ed23bcd..d64d238 100644 --- a/docs/episodes/monitoring-grafana.md +++ b/docs/guides/monitoring-grafana.md @@ -1,14 +1,14 @@ # Homelab Monitoring with Grafana and Prometheus -This page is a public-safe companion guide for a KeepItTechie video about monitoring a homelab with Grafana, Prometheus, exporters, and logs. +This guide explains monitoring a homelab with Grafana, Prometheus, exporters, and logs. -## Episode Goal +## Guide Goal -This episode teaches how monitoring gives visibility into the homelab: what is up, what is slow, what is failing, and what needs attention. +This guide teaches how monitoring gives visibility into the homelab: what is up, what is slow, what is failing, and what needs attention. The practical goal is not to build the biggest dashboard possible. The goal is to start with useful signals, understand what each monitoring component does, and avoid noisy alerts or public dashboards that reveal private infrastructure. -## What Viewers Will Learn +## What Readers Will Learn - Why monitoring matters in a homelab. - The difference between metrics, logs, and uptime checks. @@ -22,7 +22,7 @@ The practical goal is not to build the biggest dashboard possible. The goal is t Services fail. Disks fill up. Containers restart. Backups can fail. DNS can break. -Without monitoring, troubleshooting starts with guessing. With basic monitoring, viewers can answer better questions: +Without monitoring, troubleshooting starts with guessing. With basic monitoring, readers can answer better questions: - Is the service down or only slow? - Is the host overloaded? @@ -91,16 +91,16 @@ Uptime checks are often the easiest place to start because they answer a direct Checking a service does not mean publishing its real URL. Public docs should use sanitized names such as `grafana.home.example.com` and `prometheus.home.example.com`. -## Public-Safe Demo Ideas +## Public-Safe Examples -- Show the [monitoring flow diagram](../../diagrams/monitoring-flow.md). +- Open the [monitoring flow diagram](../../diagrams/monitoring-flow.md). - Walk through the [sanitized Prometheus example config](../../examples/prometheus/prometheus.yml). -- Show example dashboard categories instead of live dashboards. +- Use example dashboard categories instead of live dashboards. - Explain metrics vs logs vs uptime checks. -- Show what should not be published. +- Review what should not be published. - Use fake or demo dashboard panels if screenshots are ever added. -Do not show a live Grafana dashboard unless it is sanitized or recreated with demo data. +Do not include a live Grafana dashboard unless it is sanitized or recreated with demo data. ## Example Monitoring Plan @@ -168,7 +168,7 @@ Related examples: - [Prometheus Example Notes](../../examples/prometheus/README.md) - [Sanitized Prometheus Config](../../examples/prometheus/prometheus.yml) -## After Watching +## Next Steps - Read the [Monitoring](../../services/monitoring/README.md) service doc. - Study the [monitoring flow diagram](../../diagrams/monitoring-flow.md). diff --git a/docs/episodes/proxmox-vm-layout.md b/docs/guides/proxmox-vm-layout.md similarity index 81% rename from docs/episodes/proxmox-vm-layout.md rename to docs/guides/proxmox-vm-layout.md index 96c9542..02db68c 100644 --- a/docs/episodes/proxmox-vm-layout.md +++ b/docs/guides/proxmox-vm-layout.md @@ -1,14 +1,14 @@ # Proxmox VM Layout -This page is a public-safe companion guide for a KeepItTechie video about Proxmox, virtualization, and organizing homelab VMs by role. +This guide explains how Proxmox, virtualization, and VM role planning fit into a homelab. -## Episode Goal +## Guide Goal -The goal of this episode is to show how Proxmox acts as the virtualization layer for the lab and why organizing VMs by role makes a homelab easier to understand, back up, and rebuild. +This guide shows how Proxmox acts as the virtualization layer for the lab and why organizing VMs by role makes a homelab easier to understand, back up, and rebuild. -The episode should help viewers see Proxmox as more than a place to create random VMs. It is the compute layer that supports DNS, app hosting, monitoring, media, documentation, automation, and other workloads. +The guide helps readers see Proxmox as more than a place to create random VMs. It is the compute layer that supports DNS, app hosting, monitoring, media, documentation, automation, and other workloads. -## What Viewers Will Learn +## What Readers Will Learn - What Proxmox does in a homelab. - Why VMs are useful for learning and isolation. @@ -50,7 +50,7 @@ In a public repo, the important thing is to explain the role of each workload wi ## Grouping VMs by Role -Grouping VMs by role makes the lab easier to reason about. Viewers do not need the live inventory to understand the design. +Grouping VMs by role makes the lab easier to reason about. Readers do not need the live inventory to understand the design. Useful role groups include: @@ -78,7 +78,7 @@ docker1.home.example.com -> app.home.example.com ``` -In that example, `docker1.home.example.com` is the machine identity. The dashboard, wiki, and app names are service identities. This keeps documentation clearer because a service can move later without changing the name viewers or users remember. +In that example, `docker1.home.example.com` is the machine identity. The dashboard, wiki, and app names are service identities. This keeps documentation clearer because a service can move later without changing the name readers or users remember. ## Backups and Restore Thinking @@ -95,16 +95,16 @@ Proxmox VM The important lesson is not just "backup completed." The important lesson is whether the VM or service can be restored when needed. -## Public-Safe Demo Ideas +## Public-Safe Examples -- Show the sanitized homelab overview diagram. -- Show the service catalog grouped by role. -- Show a sanitized VM role table. +- Open the sanitized homelab overview diagram. +- Open the service catalog grouped by role. +- Use a sanitized VM role table. - Explain how service names differ from VM names. -- Show the backup flow diagram. -- Show what not to publish: live VM IDs, exact host addresses, raw exports, screenshots, and private storage paths. +- Open the backup flow diagram. +- Review what not to publish: live VM IDs, exact host addresses, raw exports, screenshots, and private storage paths. -Do not show a live Proxmox dashboard unless it is heavily sanitized or recreated with demo data. +Do not include a live Proxmox dashboard unless it is heavily sanitized or recreated with demo data. ## Example VM Role Table @@ -143,13 +143,13 @@ These are sanitized examples. They are not live VM names, VM IDs, host addresses ## Commands and Examples -These commands are examples viewers can adapt in their own lab: +These commands are examples readers can adapt in their own lab: ```bash -# Show VM list on a Proxmox host +# Show the VM list on a Proxmox host qm list -# Show container list if LXC is used +# Show the container list if LXC is used pct list # Check backup jobs from the Proxmox UI or PBS UI. @@ -158,7 +158,7 @@ pct list Review command output before sharing it publicly. VM names, VM IDs, storage names, and notes can reveal more than expected. -## After Watching +## Next Steps - Read the [Proxmox service doc](../../services/proxmox/README.md). - Study the [Current Setup](../current-setup.md) page. diff --git a/docs/episodes/reverse-proxy.md b/docs/guides/reverse-proxy.md similarity index 91% rename from docs/episodes/reverse-proxy.md rename to docs/guides/reverse-proxy.md index 36d7c9b..43b6a86 100644 --- a/docs/episodes/reverse-proxy.md +++ b/docs/guides/reverse-proxy.md @@ -1,14 +1,14 @@ # Homelab Reverse Proxy and Internal HTTPS -This page is a public-safe companion guide for a KeepItTechie video about reverse proxies, internal HTTPS, and carefully selected public access. +This guide explains reverse proxies, internal HTTPS, and carefully selected public access in a homelab. -## Episode Goal +## Guide Goal -This episode teaches how a reverse proxy gives clean service URLs, how internal HTTPS improves the homelab experience, and why public access should be limited to selected services. +This guide teaches how a reverse proxy gives clean service URLs, how internal HTTPS improves the homelab experience, and why public access should be limited to selected services. The goal is to make the web side of the lab easier to use without turning every internal dashboard into an internet-facing service. -## What Viewers Will Learn +## What Readers Will Learn - What a reverse proxy does. - Why friendly service names help. @@ -20,7 +20,7 @@ The goal is to make the web side of the lab easier to use without turning every ## Why a Reverse Proxy Matters -A reverse proxy gives one clean entry point for multiple web services. Instead of remembering ports and backend hosts, viewers can use names such as `wiki.home.example.com`, `grafana.home.example.com`, or `app.home.example.com`. +A reverse proxy gives one clean entry point for multiple web services. Instead of remembering ports and backend hosts, readers can use names such as `wiki.home.example.com`, `grafana.home.example.com`, or `app.home.example.com`. This helps with: @@ -61,7 +61,7 @@ wiki.home.example.com -> proxy forwards traffic to the wiki backend ``` -This separates service identity from backend host identity. The service name is what viewers or users type. The backend host is where the app happens to run. +This separates service identity from backend host identity. The service name is what readers or users type. The backend host is where the app happens to run. ## Private Access vs Public Access @@ -90,13 +90,13 @@ A tunnel should answer a few questions before anything is published: Tunnel credentials, connector config from the live lab, and access policy details that reveal private infrastructure should stay out of public docs. -## Public-Safe Demo Ideas +## Public-Safe Examples -- Show the [reverse proxy flow diagram](../../diagrams/reverse-proxy-flow.md). +- Open the [reverse proxy flow diagram](../../diagrams/reverse-proxy-flow.md). - Walk through the [sanitized NGINX example](../../examples/nginx/reverse-proxy-site.conf). - Walk through the [sanitized Cloudflare Tunnel example](../../examples/cloudflare-tunnel/config.example.yml). - Explain a service exposure decision table. -- Show what should not be published. +- Review what should not be published. - Avoid live dashboards unless they are sanitized or recreated with demo data. ## Example Reverse Proxy Flow @@ -159,7 +159,7 @@ dig wiki.home.example.com cat examples/nginx/reverse-proxy-site.conf ``` -## After Watching +## Next Steps - Read the [Reverse Proxy](../../services/reverse-proxy/README.md) service doc. - Study the [reverse proxy flow diagram](../../diagrams/reverse-proxy-flow.md). diff --git a/docs/learning-paths.md b/docs/learning-paths.md new file mode 100644 index 0000000..aa12bdb --- /dev/null +++ b/docs/learning-paths.md @@ -0,0 +1,99 @@ +# Learning Paths + +This page groups the repo into practical paths readers can follow. + +The KeepItTechie homelab has a lot of moving parts, but readers do not need to learn everything at once. Pick the path that matches the current goal, read the public-safe docs, and adapt the patterns in a private lab. + +## Start Here + +Use this path to understand the repo before jumping into individual services. + +1. [Current Setup](current-setup.md) +2. [Viewer Guide](viewer-guide.md) +3. [Documentation Index](docs-index.md) +4. [Glossary](glossary.md) +5. [Homelab Guides](guides/README.md) + +## Build a Basic Homelab + +This path is for readers starting from a small machine, mini PC, old desktop, or spare laptop. + +- Read [Build Your Own Homelab](build-your-own.md). +- Review [How to Read Service Pages](how-to-read-service-pages.md). +- Start with one Linux host and one simple app. +- Add DNS, backups, and monitoring before adding too many services. +- Keep private credentials and real config outside public GitHub repos. + +## Learn Networking and DNS + +This path explains how the lab routes traffic, hands out network settings, and gives services readable names. + +- [Network Design](network.md) +- [Core Infrastructure](core-infrastructure.md) +- [Homelab DNS and Pi-hole](guides/dns-pihole.md) +- [DNS Flow Diagram](../diagrams/dns-flow.md) +- [pfSense](../services/pfsense/README.md) +- [Pi-hole](../services/pihole/README.md) + +## Learn Virtualization + +This path explains how Proxmox supports the VM and container layout. + +- [Proxmox VM Layout](guides/proxmox-vm-layout.md) +- [Proxmox](../services/proxmox/README.md) +- [Core Infrastructure](core-infrastructure.md) +- [Service Catalog](service-catalog.md) +- [Service Matrix](service-matrix.md) + +## Learn Backups and Restore Testing + +This path focuses on recovery, not just backup jobs. + +- [Homelab Backups and Restore Testing](guides/backups-restore.md) +- [Storage and Backups](storage-and-backups.md) +- [Storage and Monitoring](storage-monitoring.md) +- [Backup Flow Diagram](../diagrams/backup-flow.md) +- [Proxmox Backup Server](../services/proxmox-backup-server/README.md) +- [Synology NAS](../services/synology/README.md) +- [ZFS Storage](../services/zfs-storage/README.md) + +## Learn Monitoring + +This path explains how the lab checks hosts, containers, services, metrics, and logs. + +- [Homelab Monitoring with Grafana and Prometheus](guides/monitoring-grafana.md) +- [Monitoring](../services/monitoring/README.md) +- [Monitoring Flow Diagram](../diagrams/monitoring-flow.md) +- [Prometheus Example](../examples/prometheus/README.md) +- [Screenshots Policy](screenshots-policy.md) + +## Learn Reverse Proxy and Internal HTTPS + +This path explains clean service names, internal HTTPS, and the difference between private access and selected public access. + +- [Homelab Reverse Proxy and Internal HTTPS](guides/reverse-proxy.md) +- [Reverse Proxy](../services/reverse-proxy/README.md) +- [Cloudflare Tunnel](../services/cloudflare-tunnel/README.md) +- [Reverse Proxy Flow Diagram](../diagrams/reverse-proxy-flow.md) +- [NGINX Example](../examples/nginx/README.md) +- [Cloudflare Tunnel Example](../examples/cloudflare-tunnel/README.md) + +## Learn Local AI + +This path explains how local AI fits into a Linux homelab without exposing private prompts, documents, endpoints, or model paths. + +- [Local AI on Linux](guides/local-ai.md) +- [Apps and AI](apps-and-ai.md) +- [Local AI Stack](../services/local-ai/README.md) +- [Local AI Flow Diagram](../diagrams/local-ai-flow.md) +- [Build Your Own Homelab](build-your-own.md) + +## Related Docs + +- [Current Setup](current-setup.md) +- [Build Your Own Homelab](build-your-own.md) +- [Homelab Guides](guides/README.md) +- [Documentation Index](docs-index.md) +- [Service Catalog](service-catalog.md) +- [Sanitized Examples](../examples/README.md) +- [Pre-Publish Review](pre-publish-review.md) diff --git a/docs/maintenance-checklist.md b/docs/maintenance-checklist.md index b4284ee..ef37398 100644 --- a/docs/maintenance-checklist.md +++ b/docs/maintenance-checklist.md @@ -17,7 +17,7 @@ Use this checklist for ongoing repo maintenance. For a final review before publi - [ ] Update the roadmap when phases are completed or new public docs are planned. - [ ] Update diagrams when the architecture changes. - [ ] Confirm links still point to existing files. -- [ ] Add video links after publishing KeepItTechie episodes. +- [ ] Update learning paths when guides change. ## Public Safety Review diff --git a/docs/network.md b/docs/network.md index 9127f63..57d610b 100644 --- a/docs/network.md +++ b/docs/network.md @@ -2,7 +2,7 @@ The network is built around pfSense, internal DNS, readable service names, and conservative exposure. The public examples in this repo use `10.10.0.0/24` and `home.example.com`. -For visual references, see the [DNS flow diagram](../diagrams/dns-flow.md), [reverse proxy flow diagram](../diagrams/reverse-proxy-flow.md), and [Homelab DNS and Pi-hole companion](episodes/dns-pihole.md). For terms such as LAN, VLAN, DNS, DHCP, service identity, and machine identity, use the [Glossary](glossary.md). +For visual references, see the [DNS flow diagram](../diagrams/dns-flow.md), [reverse proxy flow diagram](../diagrams/reverse-proxy-flow.md), and [Homelab DNS and Pi-hole guide](guides/dns-pihole.md). For terms such as LAN, VLAN, DNS, DHCP, service identity, and machine identity, use the [Glossary](glossary.md). ## Core Flow diff --git a/docs/overview.md b/docs/overview.md index c1b201b..a307a23 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -14,7 +14,7 @@ For a guided reading path, start with the [Viewer Guide](viewer-guide.md). To to | Keep critical services local-first | Private apps stay behind LAN, VPN, or internal DNS | | Make services easy to find | Use readable names such as `grafana.home.example.com` | | Separate roles | Firewall, DNS, storage, virtualization, monitoring, and apps each have clear ownership | -| Teach from the lab | Keep notes simple enough to explain in videos and rebuild later | +| Teach from the lab | Keep notes simple enough to explain clearly and rebuild later | | Stay public-safe | Publish architecture, not secrets or raw exports | ## High-Level Layout @@ -107,4 +107,4 @@ The simplest rule: admin tools stay private, viewer-facing or intentionally shar - [Maintenance Checklist](maintenance-checklist.md) - [Pre-Publish Review Checklist](pre-publish-review.md) - [Screenshot Policy](screenshots-policy.md) -- [YouTube Companion Series](youtube-series.md) +- [Learning Paths](learning-paths.md) diff --git a/docs/releases/v0.1.0.md b/docs/releases/v0.1.0.md index 5bb3708..50f7b5a 100644 --- a/docs/releases/v0.1.0.md +++ b/docs/releases/v0.1.0.md @@ -38,11 +38,11 @@ The docs explain patterns without publishing real public IP addresses, exact pri - Live DNS zones or exact host inventories. - Private `.env` files or runtime config. - Real restore test screenshots or private restore logs. -- Published video links for episodes that have not been released yet. +- Future guide pages that have not been written yet. ## Next Planned Improvements -- Add real published video links after companion episodes go live. +- Expand learning paths as new public-safe guides are added. - Add sanitized screenshots or demo dashboard images after screenshot review. - Add restore test evidence for selected services using public-safe notes. - Expand sanitized config examples where they teach a clear pattern. diff --git a/docs/roadmap.md b/docs/roadmap.md index 25d10d0..00fc3e5 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -53,13 +53,13 @@ Completed foundation work now covers the public-safe base docs, navigation, arch - [ ] Add a sanitized restore checklist for the media stack. - [ ] Add storage rollback examples for NAS snapshots and ZFS snapshots. -## Phase 5: Video Companion Expansion +## Phase 5: Guide Expansion -- [ ] Add links to published KeepItTechie videos. -- [ ] Add per-episode repo references. -- [ ] Add safe demo scripts or checklists where useful. -- [ ] Add viewer exercises for DNS, backups, monitoring, and reverse proxying. -- [ ] Add viewer exercises for local AI, dashboards, documentation, media, and private apps. +- [ ] Add links to new public-safe guides. +- [ ] Add topic-based repo references. +- [ ] Add public-safe checklists where useful. +- [ ] Add reader exercises for DNS, backups, monitoring, and reverse proxying. +- [ ] Add reader exercises for local AI, dashboards, documentation, media, and private apps. ## Phase 6: Sanitized Config Examples diff --git a/docs/service-matrix.md b/docs/service-matrix.md index 3c3aeae..9c5ff37 100644 --- a/docs/service-matrix.md +++ b/docs/service-matrix.md @@ -43,7 +43,7 @@ For the first deep-dive reading path, start with [Core Infrastructure](core-infr ## How To Use This Matrix -- Start here when deciding whether a service belongs in a video, diagram, or public example. +- Start here when deciding whether a service belongs in a guide, diagram, or public example. - Update it whenever a service moves hosts or changes exposure level. - Treat backup priority as a documentation priority too: critical services need clear restore notes. - Use the core infrastructure deep dives for the network, DNS, virtualization, backup, proxy, and tunnel layers. diff --git a/docs/storage-and-backups.md b/docs/storage-and-backups.md index 3db9c4d..5e877b4 100644 --- a/docs/storage-and-backups.md +++ b/docs/storage-and-backups.md @@ -2,7 +2,7 @@ Storage in the homelab has two jobs: support daily services and make recovery possible when something breaks. This page explains the public-safe architecture without publishing private shares, keys, raw exports, or live backup details. -For the storage and monitoring reading path, see [Storage and Monitoring](storage-monitoring.md). For the episode companion, see [Homelab Backups and Restore Testing](episodes/backups-restore.md). For the visual version of the backup model, see the [backup flow diagram](../diagrams/backup-flow.md). For terms such as NAS, ZFS, dataset, snapshot, scrub, backup, and restore test, use the [Glossary](glossary.md). +For the storage and monitoring reading path, see [Storage and Monitoring](storage-monitoring.md). For the guide, see [Homelab Backups and Restore Testing](guides/backups-restore.md). For the visual version of the backup model, see the [backup flow diagram](../diagrams/backup-flow.md). For terms such as NAS, ZFS, dataset, snapshot, scrub, backup, and restore test, use the [Glossary](glossary.md). ## Storage Layers diff --git a/docs/storage-monitoring.md b/docs/storage-monitoring.md index a677399..752941a 100644 --- a/docs/storage-monitoring.md +++ b/docs/storage-monitoring.md @@ -4,7 +4,7 @@ This page is the beginner-friendly entry point for storage, backups, and monitor Storage keeps services running and data available. Backups make recovery possible. Monitoring tells you when something is unhealthy before the outage becomes a mystery. -For visual references, see the [backup flow diagram](../diagrams/backup-flow.md), [monitoring flow diagram](../diagrams/monitoring-flow.md), [Homelab Backups and Restore Testing companion](episodes/backups-restore.md), and [Homelab Monitoring with Grafana and Prometheus companion](episodes/monitoring-grafana.md). For unfamiliar terms such as dataset, snapshot, scrub, metrics, and logs, use the [Glossary](glossary.md). +For visual references, see the [backup flow diagram](../diagrams/backup-flow.md), [monitoring flow diagram](../diagrams/monitoring-flow.md), [Homelab Backups and Restore Testing guide](guides/backups-restore.md), and [Homelab Monitoring with Grafana and Prometheus guide](guides/monitoring-grafana.md). For unfamiliar terms such as dataset, snapshot, scrub, metrics, and logs, use the [Glossary](glossary.md). ## Recommended Reading Order @@ -14,7 +14,7 @@ For visual references, see the [backup flow diagram](../diagrams/backup-flow.md) | 2 | Synology NAS | [Synology NAS](../services/synology/README.md) | Learn shared storage, media storage, and backup target concepts | | 3 | ZFS Storage Server | [ZFS Storage Server](../services/zfs-storage/README.md) | Learn datasets, snapshots, scrubs, and Linux storage | | 4 | Proxmox Backup Server | [Proxmox Backup Server](../services/proxmox-backup-server/README.md) | Understand VM backup and restore testing | -| 5 | Monitoring Stack | [Monitoring](../services/monitoring/README.md), [Monitoring Companion](episodes/monitoring-grafana.md) | Learn how metrics, logs, and dashboards support operations | +| 5 | Monitoring Stack | [Monitoring](../services/monitoring/README.md), [Monitoring Guide](guides/monitoring-grafana.md) | Learn how metrics, logs, and dashboards support operations | ## Stack Summary @@ -70,8 +70,8 @@ Do not document: - [Core Infrastructure](core-infrastructure.md) - [Apps and AI](apps-and-ai.md) -- [Homelab Backups and Restore Testing Companion](episodes/backups-restore.md) -- [Homelab Monitoring with Grafana and Prometheus Companion](episodes/monitoring-grafana.md) +- [Homelab Backups and Restore Testing Guide](guides/backups-restore.md) +- [Homelab Monitoring with Grafana and Prometheus Guide](guides/monitoring-grafana.md) - [Glossary](glossary.md) - [How To Read Service Pages](how-to-read-service-pages.md) - [Public-Safe Diagrams](../diagrams/README.md) diff --git a/docs/todo.md b/docs/todo.md index f63f253..6bf9537 100644 --- a/docs/todo.md +++ b/docs/todo.md @@ -20,6 +20,6 @@ This page tracks public-safe documentation ideas that may be added later. Items - [ ] Add service badges/status table - [ ] Add architecture diagram to README -- [ ] Add YouTube episode links as videos are published +- [ ] Add new guide links as public-safe docs are published - [ ] Add rebuild notes per service - [ ] Add sanitized Compose examples where safe diff --git a/docs/visual-assets-guide.md b/docs/visual-assets-guide.md index 9064aaf..dd43311 100644 --- a/docs/visual-assets-guide.md +++ b/docs/visual-assets-guide.md @@ -17,7 +17,7 @@ The tradeoff is risk. Images can leak private details that are easy to miss in a | Fake/demo dashboard screenshots | Teach layout and signal types without live infrastructure | | Cropped screenshots with no private data | Keep attention on one public-safe concept | | Mockups made from sanitized examples | Good for planned dashboards, thumbnails, or service maps | -| Social thumbnails that do not show real configs | Useful for videos without leaking lab details | +| Social preview images that do not show real configs | Useful for sharing the repo without leaking lab details | | Terminal screenshots using fake paths and fake hostnames | Safer than live terminal captures when teaching commands | ## Risky Visual Types diff --git a/docs/youtube-series.md b/docs/youtube-series.md deleted file mode 100644 index 57a0951..0000000 --- a/docs/youtube-series.md +++ /dev/null @@ -1,62 +0,0 @@ -# YouTube Companion Series - -This page maps the homelab documentation to potential KeepItTechie video topics. It is a public companion plan, not a private production schedule. - -Each topic includes: - -- Goal -- What viewers learn -- Repo references -- Safe demo ideas - -| Episode | Goal | What Viewers Learn | Repo References | Safe Demo Ideas | -|---|---|---|---|---| -| 1. Full Homelab Tour | Explain the full lab at a high level | How firewall, DNS, virtualization, storage, monitoring, media, AI, and apps fit together | `README.md`, `docs/episodes/full-homelab-tour.md`, `docs/overview.md`, `diagrams/homelab-overview.md` | Walk through the Mermaid diagram and sanitized service matrix | -| 2. Building a Homelab in Stages | Give beginners a safe build path | How to start small, add layers, and avoid copying a private setup blindly | `docs/build-your-own.md`, `docs/viewer-guide.md`, `docs/glossary.md` | Walk through stages with sanitized names such as `home.example.com` | -| 3. How the pfSense Network Is Structured | Teach the network control plane | Routing, DHCP, firewall policy, and why admin tools stay private | `docs/network.md`, `services/pfsense/README.md` | Use fake VLANs and `10.10.0.0/24` examples | -| 4. Pi-hole and Internal DNS | Show why local DNS matters | Primary/secondary DNS, service identities, and troubleshooting name resolution | `docs/episodes/dns-pihole.md`, `services/pihole/README.md`, `inventory/sanitized/hosts.example.yml` | Add a fake `grafana.home.example.com` record | -| 5. Proxmox VM Layout | Explain VM role separation | Why virtualization helps with isolation, testing, and rebuilds | `docs/episodes/proxmox-vm-layout.md`, `services/proxmox/README.md`, `docs/hardware.md` | Show a sanitized VM role table | -| 6. Proxmox Backup Server | Show backup thinking | Retention, verification, and restore testing | `docs/episodes/backups-restore.md`, `services/proxmox-backup-server/README.md`, `docs/storage-and-backups.md` | Restore a disposable demo VM or walk through a sanitized checklist | -| 7. Synology NAS vs Linux ZFS Storage | Compare storage approaches | Appliance NAS workflows versus Linux storage learning | `services/synology/README.md`, `services/zfs-storage/README.md` | Compare sanitized share and dataset examples | -| 8. Reverse Proxy and Internal HTTPS | Make services easier to reach | DNS aliases, TLS, proxy routing, and private admin boundaries | `docs/episodes/reverse-proxy.md`, `services/reverse-proxy/README.md`, `docs/network.md` | Build a fake `app.home.example.com` route | -| 9. Cloudflare Tunnel Done Safely | Explain selective public access | Why public access should be intentional and documented | `services/cloudflare-tunnel/README.md`, `docs/security-notes.md` | Review a public-access decision table without showing credentials | -| 10. Monitoring the Homelab with Grafana | Build useful visibility | Metrics, logs, exporters, and uptime checks | `docs/episodes/monitoring-grafana.md`, `services/monitoring/README.md`, `docs/service-matrix.md` | Show a recreated dashboard with fake hostnames | -| 11. Local AI on Linux | Explain local inference | GPU role, model storage, Open WebUI, and local-first AI tooling | `docs/episodes/local-ai.md`, `docs/apps-and-ai.md`, `services/local-ai/README.md` | Send a placeholder request to `https://ai.home.example.com/v1` | -| 12. Self-Hosted Dashboard | Show daily lab navigation | Service grouping, dashboard links, health checks, and public-safe dashboard design | `docs/apps-and-ai.md`, `services/glance/README.md`, `diagrams/homelab-overview.md` | Build a sanitized dashboard section with fake links | -| 13. Building a Personal Wiki | Show documentation habits | Public/private namespaces, runbooks, content planning, and safe publishing boundaries | `docs/apps-and-ai.md`, `services/wiki/README.md` | Create fake public/private namespace examples | -| 14. Nextcloud Private Cloud | Explain self-hosted file sync | User files, app data, database backups, reverse proxy dependency, and restore planning | `docs/apps-and-ai.md`, `services/nextcloud/README.md` | Use fake files and a sanitized backup checklist | -| 15. Media Stack Overview | Explain a multi-app media workflow | Plex, Servarr-style automation, Tautulli, Tdarr, storage dependencies, and private dashboards | `docs/apps-and-ai.md`, `services/media-stack/README.md` | Map fake media paths and service roles | -| 16. AWX and Ansible Automation | Turn admin tasks into repeatable jobs | Inventories, playbooks, credentials, job templates, and guardrails | `docs/apps-and-ai.md`, `services/automation-awx/README.md`, `inventory/sanitized/hosts.example.yml` | Run a read-only fake inventory report | -| 17. Building Local-First Personal Apps | Connect infrastructure to real workflows | Private app hosting, data boundaries, backups, and local AI support | `docs/apps-and-ai.md`, `services/financehq/README.md`, `services/careerfill/README.md` | Use fake financial and job-search sample data | - -## Episode Format - -Each topic can follow a simple walkthrough format: - -```text -Problem: -What pain point does this solve? - -Architecture: -Where does it sit in the lab? - -Build or walkthrough: -What are the key pieces? - -Security: -What should viewers avoid exposing? - -Demo: -What does success look like? - -Viewer exercise: -What can viewers try in their own lab? -``` - -## Publishing Notes - -- Episode companion pages live in [docs/episodes](episodes/README.md). -- Add video links back into this file after episodes are published. -- Keep raw admin screens, real domains, public IPs, and credentials out of recordings. -- Use sanitized diagrams and fake data in repeatable demos. -- Use `home.example.com` service names and generic paths such as `/mnt/storage/appdata`. diff --git a/services/cloudflare-tunnel/README.md b/services/cloudflare-tunnel/README.md index 2116fff..3c1ddde 100644 --- a/services/cloudflare-tunnel/README.md +++ b/services/cloudflare-tunnel/README.md @@ -104,7 +104,7 @@ Sanitized service exposure table: ## Related Sanitized Examples -- [Homelab Reverse Proxy and Internal HTTPS Companion](../../docs/episodes/reverse-proxy.md) +- [Homelab Reverse Proxy and Internal HTTPS Guide](../../docs/guides/reverse-proxy.md) - [Cloudflare Tunnel config shape](../../examples/cloudflare-tunnel/config.example.yml) - [Cloudflare Tunnel example notes](../../examples/cloudflare-tunnel/README.md) - [Reverse proxy flow diagram](../../diagrams/reverse-proxy-flow.md) diff --git a/services/financehq/README.md b/services/financehq/README.md index eaee6ef..1ac1b39 100644 --- a/services/financehq/README.md +++ b/services/financehq/README.md @@ -88,7 +88,7 @@ Public-safe boundary table: - Do not publish real financial data. - Treat logs and imports as sensitive. - Do not commit private database paths or dumps. -- Use fake demo data in videos and docs. +- Use fake demo data in public docs. ## Common Mistakes to Avoid diff --git a/services/glance/README.md b/services/glance/README.md index 19bb3e1..dc34c38 100644 --- a/services/glance/README.md +++ b/services/glance/README.md @@ -115,4 +115,4 @@ Sanitized dashboard grouping: - Add a sanitized dashboard example file. - Add a dashboard-to-service matrix. -- Add screenshot guidance for public videos. +- Add screenshot guidance for public docs. diff --git a/services/local-ai/README.md b/services/local-ai/README.md index 8a77882..4790b0c 100644 --- a/services/local-ai/README.md +++ b/services/local-ai/README.md @@ -8,7 +8,7 @@ The local AI stack provides private, Linux-first AI experimentation using a GPU Local AI is useful for privacy, control, learning, and content creation. It lets viewers understand how models run, why GPU memory matters, how local APIs can mimic hosted AI APIs, and where self-hosted AI fits into a practical homelab. -For KeepItTechie, this stack also supports videos about Linux GPU setup, local-first tools, automation, and practical AI workflows without treating every prompt as cloud-bound. +For KeepItTechie, this stack also supports Linux GPU setup notes, local-first tools, automation, and practical AI workflows without treating every prompt as cloud-bound. ## Where It Fits in the Homelab @@ -126,7 +126,7 @@ The example shows the API pattern only. Do not commit real credentials. ## Related Docs -- [Local AI on Linux Companion](../../docs/episodes/local-ai.md) +- [Local AI on Linux Guide](../../docs/guides/local-ai.md) - [Local AI flow diagram](../../diagrams/local-ai-flow.md) - [Apps and AI](../../docs/apps-and-ai.md) @@ -134,4 +134,4 @@ The example shows the API pattern only. Do not commit real credentials. - Add a sanitized model inventory template. - Add GPU monitoring dashboard ideas. -- Add a local AI demo checklist for KeepItTechie videos. +- Add a local AI lab checklist with public-safe example prompts. diff --git a/services/monitoring/README.md b/services/monitoring/README.md index b5d9fe1..c8d1da1 100644 --- a/services/monitoring/README.md +++ b/services/monitoring/README.md @@ -128,7 +128,7 @@ Public-safe dashboard ideas: ## Related Sanitized Examples -- [Homelab Monitoring with Grafana and Prometheus Companion](../../docs/episodes/monitoring-grafana.md) +- [Homelab Monitoring with Grafana and Prometheus Guide](../../docs/guides/monitoring-grafana.md) - [Prometheus scrape config](../../examples/prometheus/prometheus.yml) - [Prometheus example notes](../../examples/prometheus/README.md) - [Monitoring flow diagram](../../diagrams/monitoring-flow.md) diff --git a/services/reverse-proxy/README.md b/services/reverse-proxy/README.md index 3e8d5a6..e8ca796 100644 --- a/services/reverse-proxy/README.md +++ b/services/reverse-proxy/README.md @@ -111,7 +111,7 @@ This is a placeholder. Do not copy live certificate paths, real backend names, o ## Related Sanitized Examples -- [Homelab Reverse Proxy and Internal HTTPS Companion](../../docs/episodes/reverse-proxy.md) +- [Homelab Reverse Proxy and Internal HTTPS Guide](../../docs/guides/reverse-proxy.md) - [NGINX reverse proxy server block](../../examples/nginx/reverse-proxy-site.conf) - [NGINX example notes](../../examples/nginx/README.md) - [Reverse proxy flow diagram](../../diagrams/reverse-proxy-flow.md) diff --git a/services/wiki/README.md b/services/wiki/README.md index e6c739c..3410401 100644 --- a/services/wiki/README.md +++ b/services/wiki/README.md @@ -53,7 +53,7 @@ Example: wiki.home.example.com -> proxy.home.example.com ``` -Private admin pages should require authentication. Public pages should be reviewed before publishing or linking from videos. +Private admin pages should require authentication. Public pages should be reviewed before publishing or linking from public docs. ## Key Responsibilities