157 lines
4.3 KiB
Markdown
157 lines
4.3 KiB
Markdown
---
|
|
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/)
|