mkuthan/homelab-public: A Proxmox and Ansible Homelab You Can Read, Not Deploy
Homelab infrastructure as a code (IaaC)
At a glance
- What is it?
- This is one person's working homelab, published as HCL and Ansible roles under AGPL-3.0. It is a reference architecture and a service catalogue, not a distribution, and the README makes no promise that it will run on your hardware.
- Who is it for?
- Adopt this as a reading list and a pattern library if you already run Proxmox, Tailscale and Ansible and want to see how one operator split provisioning from configuration. Do not adopt it as a deployable stack: there is no release, no module interface, no variable contract and no upgrade path, and the Terraform targets one specific Proxmox cluster plus one GCP project.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 10 days ago.
- What is it written in?
- Mainly HCL, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What mkuthan/homelab-public actually is
The README opens with a three-line manifesto: self-host services and data, keep it simple, define infrastructure as code. The repository is the working configuration behind that manifesto, written primarily in HCL, with Ansible handling service installation and configuration. Two environments are named. The primary one is a Proxmox cluster, referred to in the README as Wieprz. A second, older environment called Bekasow was built on Raspberry Pi and, according to the README, is still in use. The audience is narrow and self-selecting. This is not aimed at a team looking for a turnkey self-hosting bundle. It is aimed at someone who already owns a hypervisor, has opinions about DNS and backups, and wants to read a complete worked example rather than a tutorial. The blog at mkuthan.github.io is presented as the narrative companion to the code, which tells you where the author expects explanation to live.
The split between Terraform and Ansible
The division of labour is stated plainly. Terraform defines Linux containers on Proxmox, a virtual private server in GCP, offsite backup buckets in GCP, and Tailscale access control lists. Ansible playbooks manage the services and their configuration. That boundary is the most transferable idea in the repository. Provisioning is declarative and lives in state; service configuration is procedural and lives in roles. The Tailscale ACL entry is worth pausing on. Putting access control in Terraform rather than in the Tailscale admin console means network policy is versioned alongside the machines it governs, and a change to who can reach what shows up in the same diff as the container it affects. The README points to the terraform directory for the resource definitions and to ansible/roles for the service side, so the layout is the documentation. Nothing in the supplied material describes a module interface, a variables contract, or a state backend, and those are the parts a second operator would need before reusing any of it.
The Ansible role catalogue is the real content
The README lists roles for Adguard DNS, Apt Cacher NG, Backup Ninja, Bambuddy, Docker, Fluent Bit, Frigate, Grafana, Grafana Agent, Gramps, Hyperion NG, Immich, Jellyfin, Kodi, Loki, Mailrise, Mosquitto, NUT, Omada Software Controller, Open Web UI, Paperless NGX, Proxmox Backup Server, Prometheus, Raspotify, RClone, Samba, SearXNG, Shairport, Stirling PDF, Tailscale, Traefik, Transmission, Uptime Kuma, Vaultwarden, Whoogle and Zigbee2MQTT, and says there are more under ansible/roles. Read that list as an inventory of what one household actually runs, not as a supported feature set. The observability pair is the clearest signal of intent: Prometheus and Grafana Agent on the collection side, Loki for logs, Grafana for the front end, with Fluent Bit handling log shipping. Traefik appears as the ingress layer, which implies the services behind it are addressed by hostname rather than port. Apt Cacher NG and RClone suggest the author cares about bandwidth and offsite copies. Frigate and Zigbee2MQTT place the whole thing in a physical house with cameras and sensors, which is a different constraint set from a datacenter lab.
Getting it running means reading directories, not running one command
There is no install command in the supplied material. No Makefile target, no bootstrap script, no documented variable file. The README gives two directory pointers and nothing else: terraform for the resource definitions, ansible/roles for the service roles. That is the honest state of a personal repository, and it should shape expectations. A reader who wants to reproduce any part of it has to open the Terraform files and identify which provider and resource types are in use, then map those onto their own Proxmox endpoint and credentials. On the Ansible side, the roles are the unit of reuse, so the practical path is to copy one role, read its tasks, and adjust the variables it references. The documentation directory is where the operational detail lives: network.md covers VPN, DNS and VLAN, hardware.md covers network equipment, servers and disks, backup.md covers Proxmox Backup Server and offsite backups, and there are separate notes for cameras, IoT, Home Assistant, photovoltaics, Proxmox, Raspberry Pi, SSH and media. Those files are the closest thing to a setup guide, and they describe one installation rather than a general procedure.
Where this repository will not help you
The failure mode is straightforward. This is a single-operator configuration tied to specific hardware, and the README names the hardware: a Proxmox cluster and a Raspberry Pi. Nothing in the supplied material indicates parameterised variables, version pinning, or a supported upgrade path between releases. There are no releases at all in the retrieved data, so there is no changelog to consult before pulling a change and no way to reason about what a given commit expects. If you run a different hypervisor, or you run Proxmox but with a different storage layout, the Terraform will not map cleanly and you will be editing rather than applying. The AGPL-3.0 licence is also a real consideration for anyone thinking about lifting a role into a product; the obligation attaches to what you copy, and this article is not legal advice on how far that reaches. A second limitation is quieter: a homelab optimised for one household can encode assumptions about a single subnet, a single DNS resolver and a single backup target that are invisible until you try to run it somewhere else.
How it compares to a packaged self-hosting stack
The obvious alternative is a project like Proxmox Helper Scripts, or a Compose-based bundle such as the ones built around a single docker-compose.yml plus a reverse proxy. Those take the opposite approach: they assume you want the services more than you want to understand the wiring, and they hand you a script or a compose file that brings up a working instance with minimal reading. mkuthan/homelab-public does the reverse. It assumes you want the wiring, and it gives you the Terraform resources and Ansible roles that produced one particular working instance without packaging them for anyone else. The trade is legibility against reproducibility. A helper script gets you to a running Jellyfin faster; this repository shows you how Jellyfin, Traefik, Prometheus, Loki and the backup path fit together in one operator's design, which is a different kind of value and a slower one to extract.
Maintenance cost and what the licence means in practice
The repository is AGPL-3.0 and is not archived, with a last push in September 2026 in the supplied data. A homelab of this size carries ongoing cost regardless of who wrote it: every listed role is a service that needs updating, and the observability stack alone (Prometheus, Grafana Agent, Loki, Grafana, Fluent Bit) is five moving parts before you count the things it watches. If you fork it, you inherit that surface area without inheriting the author's context. The AGPL-3.0 terms are the ones to read before copying roles into anything you distribute or expose as a network service, and the repository as published carries no warranty. The realistic maintenance model for a reader is not to track upstream but to mine it once: take the Terraform and Ansible split as a pattern, take two or three roles whose approach you like, and leave the rest. That keeps the upgrade burden proportional to what you actually adopted.
Editorial conclusion
Adopt this as a reading list and a pattern library if you already run Proxmox, Tailscale and Ansible and want to see how one operator split provisioning from configuration. Do not adopt it as a deployable stack: there is no release, no module interface, no variable contract and no upgrade path, and the Terraform targets one specific Proxmox cluster plus one GCP project. Before copying anything, open terraform/ and ansible/roles, confirm which resource types map to your own Proxmox version, and check that the Tailscale ACL entries in Terraform match the tailnet you actually control. The AGPL-3.0 licence applies to whatever you copy, and the repository carries no warranty of any kind.
Community notes