RackPeek: A YAML-Backed Inventory for Home Labs

The problem RackPeek picks, and the ones it refuses

Home labs accumulate facts that no single tool owns. A rack of machines, the services running on them, the VLANs and subnets connecting them, and the relationships between all three. Spreadsheets go stale because nobody wants to edit them. Wiki pages drift from reality. Enterprise CMDB products solve this at a scale and cost that a two-rack setup cannot justify. RackPeek's stated scope is the gap in between: track hardware, services, networks and their relationships, in a way the README describes as scriptable and reusable, without what it calls enterprise bloat or proprietary lock-in. The audience is named directly in the project's own core values, which say the tool is optimized for home labs and self-hosted environments rather than enterprise CMDBs or corporate documentation workflows. That sentence is the whole product thesis. If your inventory problem is a compliance audit trail with sign-off, RackPeek is aimed elsewhere on purpose, and no amount of configuration will turn it into that tool.

One YAML file is the database

The architecture is unusually easy to state. The README notes that RackPeek stores its state in YAML, and the Docker examples mount a config directory containing a single file, config.yaml. There is no external database service to run, no migration step described in the README, and no schema server. The web UI and the CLI read and write the same file. That choice drives most of the project's behaviour. Backups are file copies. Version history is whatever your git repository or filesystem snapshots already provide. Reviewing a change means reading a diff. It also means the file is the concurrency boundary: the README does not describe locking, so if you edit config.yaml in an editor while the container is running, the file on disk and the running process can diverge. Treat the mounted directory as the single writer, and prefer the CLI or the web UI over hand-editing while the service is up. The README also does not describe a documented schema version field or a migration path between the 1.x and 2.0.0 file layouts, so an upgrade plan should include taking a copy of config.yaml first.

Getting it running: two Docker paths and a health endpoint

The README gives a named volume form and a bind mount form. The named volume version creates a volume and runs the image with port 8080 published and the volume mounted at /app/config. The bind mount version replaces the volume argument with a host path. A compose file is provided as well, using the image aptacode/rackpeek:latest, the same port mapping, restart set to unless-stopped, and a healthcheck that curls http://localhost:8080/health every 30 seconds with a 5 second timeout, a 15 second start period and 3 retries. That health endpoint is useful beyond compose: it is the cheapest way to confirm the container is actually serving before you point a reverse proxy at it. For anything beyond a scratch install, pin the image tag rather than using latest, because the project shipped 2.0.0 after 1.4.0 and the README does not promise that a config.yaml written under 1.x is read unchanged by 2.0.0. The documentation index points to an Installation Guide and a CLI Commands Reference; those are where the actual subcommand names live, and the README itself does not enumerate them.

The Ansible generator is the feature that changes the argument

Most documentation tools produce output for humans. RackPeek ships a documented Ansible Inventory Generator, which means the inventory you maintain can become the input to your configuration management instead of a parallel copy of it. That is the difference between a document that decays and a source of truth that earns its maintenance cost. The README links the guide but does not reproduce the generator's flags or the shape of the emitted inventory, so the group names, host variable names and file layout it produces are things you have to read the guide to learn. Do that before you populate config.yaml, not after. If the generator emits groups that do not match your playbook naming, you will either rewrite your playbooks or maintain a translation layer, and both of those costs land on you rather than on RackPeek.

Where RackPeek is the wrong tool

RackPeek records what you tell it. The README describes discovery in the project description, but the material available here does not document an agent, a network scan, or an SNMP poller that populates the inventory on its own. Assume declared state until you read the CLI reference and find otherwise. That single fact rules RackPeek out for anyone whose problem is not knowing what is on the network in the first place. It is also a poor fit for multi-operator environments that need per-change attribution. A YAML file in a git repository gives you commit authorship, but the README describes no role model, no approval step and no audit log inside the tool. And it is a poor fit for estates large enough that a single file becomes a merge conflict, because nothing in the README describes splitting inventory across multiple files or merging them. The project's own core values call the scope intentionally narrow; that is a design commitment, not a backlog item.

NetBox is the honest comparison, and the difference is the data model

NetBox is the obvious alternative and the comparison is not close on features, only on fit. NetBox runs on PostgreSQL and Redis and models infrastructure as a relational schema with IP address management, prefix hierarchy, device roles, cable tracing and a REST API backed by that schema. Its data model is the product. RackPeek's data model is a YAML document you can open in an editor, and its selling point is that you can read and migrate it without a running service. The practical difference shows up in two places. First, querying: NetBox can answer a question like which interfaces sit inside a prefix without you having written that relationship down, because the schema encodes it; RackPeek answers only what you recorded as a relationship. Second, operations: NetBox is a service with a database to back up and upgrade, while RackPeek is a container with a file to copy. Pick NetBox when the relationships are the hard part and you have the operational appetite for a database. Pick RackPeek when the hard part is simply that nobody has written anything down.

Licence, maintenance and what a 2.0.0 bump implies

RackPeek is AGPL-3.0. For self-hosted personal use that is a non-issue. For anyone who intends to wrap it in a hosted service or embed it in a product, the network copyleft terms of the AGPL are the part to read carefully, and that is a question for your own counsel rather than a conclusion this article can reach. On maintenance, the release cadence visible in the material is roughly monthly across 1.3.1, 1.4.0 and 2.0.0, with the 2.0.0 release landing on the same day as the most recent push to main. A major version bump on an actively developed tool is the point where upgrade cost is highest, and the README's versioning document is the place that should say what changed. The README also states that the roadmap for the next wave of features is being discussed and invites users to a questionnaire and a Discord, which is a reasonable signal that interfaces may still move. Practically, that means pinning the image tag, keeping config.yaml in version control, and reading the versioning document before each bump. The project publishes no telemetry and states that what runs on your infrastructure stays on your infrastructure, so the upgrade risk is confined to your own file.

Editorial conclusion

Adopt RackPeek if you run a home lab or small self-hosted estate and want your inventory readable in a text editor, diffable in git, and exportable into Ansible inventory. Do not adopt it if you need a relational CMDB with change history, approval workflows, or discovered rather than declared state; the README explicitly positions the project away from enterprise CMDB use. Before committing, open the CLI Commands Reference and the Ansible Inventory Generator Guide, then verify two things in a scratch container: that config.yaml round-trips through the commands you plan to script, and that the generated Ansible inventory matches the host and group naming your playbooks already use.

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. Timmoth/RackPeek on GitHub