homelab

My homelab, as code. A bare-metal Kubernetes cluster managed with GitOps, a Proxmox host for everything that is not in Kubernetes yet, and a NAS for storage and backups. Later also Terraform, Ansible, Crossplane and AWS.

The lab is where I learn platform engineering by doing it: I act as both the platform team and the development team, follow the same practices I would at work, and write about it on my blog at magelssen.io/blog.

These docs are the Markdown files in docs/ of the repository.

The docs

SectionWhat is in it
ArchitectureHow the homelab fits together: hardware, network, storage, and the technology choices
Kubernetes clusterThe GitOps flow, the nodes and secrets
ServicesEvery service and where it runs, and the ones outside Kubernetes (Uptime Kuma)
OperationsRunning it: backups, dependency updates and versions
DevelopmentHow changes are made: the GitHub repository and Claude as an agent
DecisionsArchitecture decision records: why each larger choice was made, and what was rejected

Repository

PathContents
kubernetes/Flux entrypoint, cluster infrastructure and apps. See kubernetes/README.md.
terraform/Proxmox and AWS as code. Not started.
ansible/Node and NAS configuration. Not started.
docs/These docs.
hugo/The docs website: Hugo config and templates. See hugo/README.md.
scripts/Helper scripts run locally, such as generating the read-only kubeconfig for Claude.
.github/Workflows, issue forms, the pull request template, labels, code owners, the Renovate configuration and the ruleset for main. See GitHub repository.
CLAUDE.md filesInstructions for Claude Code, at the root and per directory.