Architecture

A high-level look at how the homelab is structured. The goal is a setup that's maintainable, recoverable, and easy to reason about.

Core Principles

Containerization

Services run in containers. This keeps them isolated from each other and from the host, makes updates and rollbacks straightforward, and means the environment can be reproduced if hardware needs to be replaced.

Reverse Proxying

All external-facing traffic goes through a single reverse proxy (Caddy). This handles TLS termination, routing, and access control in one place. Services don't need to manage their own certificates.

Observability

Logs and metrics are collected centrally. The goal is to know when something is wrong before it becomes a problem, and to have enough context to diagnose issues when they do occur.

Backups

Anything worth keeping is backed up. Backup strategy considers both local redundancy and off-site copies. Recovery is tested periodically — a backup that hasn't been restored is an assumption, not a guarantee.

Documentation

If a service is running, there should be enough documentation to rebuild it from scratch or hand it off to a future version of myself who doesn't remember the original decisions.

General Structure

Internet
  └── Reverse Proxy (Caddy, TLS termination)
        ├── Public-facing services
        └── Internal services
              ├── Monitoring stack
              ├── Automation tooling
              ├── Media services
              └── Development utilities

---

Network topology and specific configuration details are not documented here for security reasons.