homelab-public: a Proxmox homelab kept as code

Three manifesto lines and exactly two tools

The project is described as infrastructure as code for a self-hosted setup, and the principles are written as three lines: self-host services and data, keep it simple stupid, and define infrastructure as code.

The tools list matches the discipline. There is Terraform and there is Ansible, and nothing else is named as a category. Docker appears, but as a service being configured rather than as the substrate the whole repository is built on.

That combination is a deliberate split. Terraform provisions and describes infrastructure: containers, cloud resources and access control lists. Ansible configures what runs inside: thirty-six services with their own configurations.

The stated purpose is to experiment with and manage technologies and services in a controlled environment. That is worth reading as an admission that the homelab is a test bed first and a production stack second, which is why the service list includes software a careful administrator would not deploy, and why the documentation exists at all.

The repository is published under AGPL-3.0, which is a heavier licence than most infrastructure examples carry, and it is worth understanding what that means before you fork someone's household configuration.

Terraform provisions four kinds of thing

The Terraform side is short, and the short list is informative.

It defines Linux containers on Proxmox. It defines a virtual private server in Google Cloud. It defines offsite backup buckets in Google Cloud. And it defines Tailscale access control lists.

Four resource types, and three of them point outward. The cloud resources exist for two reasons that matter: a virtual private server that is not in the house, and backup buckets that are not in the building. The Tailscale ACLs exist because the house has several networks that need to reach each other without being merged.

That gives you the shape of the design. Local compute is Proxmox containers, remote compute is one cloud server, disaster recovery is offsite buckets, and the network is a mesh with an explicit policy rather than port forwarding into the home.

The details live in the `terraform` directory, which the README points to instead of summarising, so the state layout and variable structure are there to be read. Nothing in the README suggests a variable file you can copy wholesale, which is consistent with a network that has been changed many times.

Ansible manages thirty-six services

The Ansible side is a role per service, and the list is the most useful thing in the repository because it shows what a working household stack actually contains.

The network and entry points are there: Adguard DNS, Traefik as the reverse proxy, Tailscale for the mesh, and an Omada Software Controller for the switching. Storage and backup come from Samba, RClone and Backup Ninja, plus Proxmox Backup Server on the hypervisor side. Monitoring is Prometheus with Grafana and Grafana Agent, Loki for logs, Fluent Bit as the collector and Uptime Kuma for availability.

Then there is the media half: Jellyfin, Kodi, Transmission, Raspotify and Shairport. The document half: Paperless NGX and Stirling PDF. The photograph half: Immich with Frigate for camera detection. The automation half: Home Assistant alongside Zigbee2MQTT, Mosquitto for messaging and NUT for power. And the practical half: Apt Cacher NG for package caching, Vaultwarden for passwords, Whoogle and SearXNG for search, Open Web UI as a local chat interface, Gramps for genealogy, Hyperion NG for ambient lighting, Bambuddy and Mailrise as smaller additions.

The roles directory is where the configurations live, and it is the part you would actually reuse.

The first Raspberry Pi is still in service

One line in the introduction says more about the project than the whole service list.

The primary homelab is built on a Proxmox cluster with virtualisation. The first homelab, built on a Raspberry Pi years ago, is still in use.

A configuration repository that has survived several hardware generations is the rarest thing in this genre. Most published homelabs describe a build; this one describes an arrangement that has been migrated, and the older hardware was good enough to keep rather than recycle.

It also explains the tone of the documentation. Notes about network, hardware and backup are written for someone who has already made the mistakes, which is why they exist at all. The README frames them with a line about code not telling the whole story and documentation doing so, and then lists eleven of them.

The Raspberry Pi note is listed among them, covering Raspberry Pi OS specifically, alongside a separate Proxmox note on managing virtual machines and Linux containers. Two hypervisor notes in a home lab of this size says the migration from the Pi to Proxmox was substantial.

Eleven notes, written by the person who owns the network

The documentation is a list of topics rather than a site, and each entry names what it covers.

Network covers the VPN, DNS and VLANs. Hardware covers network equipment, servers and disks. CCTV covers cameras and motion detection. IoT covers ZigBee coordinators, sensors and switches. Home Assistant covers automations and dashboards. Photovoltaics covers solar panels and batteries.

The rest are infrastructure notes: Proxmox for virtual machine and container management, Raspberry Pi for its operating system, backup covering both the Proxmox backup server and offsite backups, SSH for remote access to servers, and media covering the TV box, streaming and audio.

Reading the list tells you the shape of the house. There are cameras with motion detection, solar panels with batteries, a ZigBee mesh, a TV box, and a VLAN structure. Those are the constraints every configuration in the roles directory is written against, and they are the part you cannot copy.

The README also points to a blog tagged for the homelab, which is where the longer explanations live. The repository itself stays short on prose.

The repository is small, and its linter is for prose

The tree is nine entries, and one of them tells you what the project considers its output.

There is an `ansible/` directory, a `terraform/` directory, a `docs/` directory, a README and a LICENSE, plus a `.gitattributes` and a `.gitignore`. There is also a `.ansible/` directory, which is Ansible's own repository-local configuration, so collection and role paths are pinned in the repository rather than in your home directory.

The notable entry is `.markdownlint.yaml`. This is a repository whose primary human-readable output is prose, so the notes are linted with a Markdown linter the way code would be. That is a small signal about how the documentation is treated.

What is absent is as telling as what is present. There is no CI configuration, no container build, no Makefile and no test suite. A pull request to this repository gets a human reading it, which for infrastructure means the review is the safety mechanism rather than an automated plan.

The repository publishes no GitHub releases, and the last push to main is dated 2026-09-18.

Editorial conclusion

Read this repository if you are building a Proxmox homelab and want to see how one person wires DNS, reverse proxying, media, monitoring, storage and a private network together, since the roles directory is a working reference for the parts everyone gets wrong. Do not expect a turnkey deployment, because the configuration is shaped around one household's network, VLANs and cameras. Before you copy anything, read the network and hardware notes first, and note the AGPL-3.0 licence, which matters if you publish a fork of someone's infrastructure.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. mkuthan/homelab-public on GitHub
4. Project website
5. README