first version of the knowledge base :)

2026-03-14 11:41:54 +01:00
commit 27965301ad
47 changed files with 4356 additions and 0 deletions
--- a/Systems/homelab/homelab-architecture.md
+++ b/Systems/homelab/homelab-architecture.md
@@ -0,0 +1,156 @@
+---
+title: Homelab Architecture
+description: Reference architecture for building a maintainable homelab with clear trust zones and operational boundaries
+tags:
+  - homelab
+  - architecture
+  - infrastructure
+category: systems
+created: 2026-03-14
+updated: 2026-03-14
+---
+
+# Homelab Architecture
+
+## Introduction
+
+A homelab architecture should make experimentation possible without turning the environment into an undocumented collection of one-off systems. The most effective designs separate compute, networking, storage, identity, and operations concerns so each layer can evolve without breaking everything above it.
+
+## Purpose
+
+This document describes a reusable architecture for:
+
+- Self-hosted services
+- Virtualization and container workloads
+- Secure remote access
+- Monitoring, backup, and update workflows
+
+## Architecture Overview
+
+A practical homelab can be viewed as layered infrastructure:
+
+```text
+Edge and Access
+  -> ISP/router, firewall, VPN, reverse proxy
+
+Network Segmentation
+  -> management, servers, clients, IoT, guest
+
+Compute
+  -> Proxmox nodes, VMs, container hosts
+
+Platform Services
+  -> DNS, reverse proxy, identity, secrets, service discovery
+
+Application Services
+  -> dashboards, git forge, media, automation, monitoring
+
+Data Protection
+  -> backups, snapshots, off-site copy, restore testing
+```
+
+## Recommended Building Blocks
+
+### Access and identity
+
+- VPN or zero-trust access layer for administrative entry
+- SSH with keys only for infrastructure access
+- DNS as the primary naming system for internal services
+
+### Compute
+
+- Proxmox for VM and LXC orchestration
+- Dedicated container hosts for Docker or another runtime
+- Utility VMs for DNS, reverse proxy, monitoring, and automation
+
+### Storage
+
+- Fast local storage for active workloads
+- Separate backup target with different failure characteristics
+- Clear distinction between snapshots and real backups
+
+### Observability and operations
+
+- Metrics collection with Prometheus-compatible exporters
+- Dashboards and alerting through Grafana and Alertmanager
+- Centralized backup jobs and restore validation
+- Controlled update workflow for host OS, containers, and dependencies
+
+## Example Layout
+
+```text
+VLAN 10  Management   hypervisors, switches, storage admin
+VLAN 20  Servers      reverse proxy, app VMs, databases
+VLAN 30  Clients      desktops, laptops, admin workstations
+VLAN 40  IoT          cameras, smart home, media devices
+VLAN 50  Guest        internet-only devices
+```
+
+Service placement example:
+
+- Reverse proxy and DNS on small utility VMs
+- Stateful applications in dedicated VMs or clearly documented persistent containers
+- Monitoring and backup services isolated from guest and IoT traffic
+
+## Configuration Example
+
+Example inventory model:
+
+```yaml
+edge:
+  router: gateway-01
+  vpn: tailscale
+
+compute:
+  proxmox:
+    - pve-01
+    - pve-02
+    - pve-03
+  docker_hosts:
+    - docker-01
+
+platform:
+  dns:
+    - dns-01
+  reverse_proxy:
+    - proxy-01
+  monitoring:
+    - mon-01
+  backup:
+    - backup-01
+```
+
+## Troubleshooting Tips
+
+### Services are easy to deploy but hard to operate
+
+- Add inventory, ownership, and restore notes
+- Separate platform services from experimental application stacks
+- Avoid hiding critical dependencies inside one large Compose file
+
+### Changes in one area break unrelated systems
+
+- Recheck network boundaries and shared credentials
+- Remove unnecessary coupling between storage, reverse proxy, and app hosts
+- Keep DNS, secrets, and backup dependencies explicit
+
+### Remote access becomes risky over time
+
+- Review which services are internet-exposed
+- Prefer tailnet-only or VPN-only admin paths
+- Keep management interfaces off user-facing networks
+
+## Best Practices
+
+- Design around failure domains, not only convenience
+- Keep a small number of core platform services well documented
+- Prefer simple, replaceable building blocks over fragile all-in-one stacks
+- Maintain an asset inventory with hostnames, roles, and backup coverage
+- Test recovery paths for DNS, identity, and backup infrastructure first
+
+## References
+
+- [Proxmox VE Administration Guide: Cluster Manager](https://pve.proxmox.com/pve-docs/chapter-pvecm.html)
+- [Docker: Docker overview](https://docs.docker.com/get-started/docker-overview/)
+- [Tailscale: What is Tailscale?](https://tailscale.com/kb/1151/what-is-tailscale)
+- [Prometheus](https://prometheus.io/)