Build a Homelab Service Catalog Before You Forget Everything
Tech GuruQuick Answer
Start with a small, access-controlled catalog that names each important service's owner, runtime, data, dependencies, backup, and recovery instructions. Keep secret references rather than secret values, and maintain an offline-readable copy outside the lab it describes. A dashboard can consume those records but cannot replace them. Reconcile five critical services against actual deployments and ask another person to use the records during recovery before adding discovery or a larger catalog platform.
The Reader Question
What runs where, who uses it, and how do I recover it later?
This guide is for the person who has become the only map of a growing home lab. It assumes you can inventory hosts, DNS names, data locations, and backups, but it does not require a configuration management database. The first deliverable is a small offline-readable catalog that helps another person understand impact and recovery without exposing credentials.
Before You Start: Safe Defaults
- Include DNS names, ports, host, storage path, database, reverse proxy route, and backup method.
- Keep the catalog accessible if the homelab is down.
- Review it after every new service, migration, decommission, and backup change.
- Use Docker labels or discovery later; do not let auto-discovery replace human context.
Reference Model
The reference model below shows the practical order for homelab service catalog before you forget everything. Open each step for the operational detail behind the diagram.
Decision Matrix
| Choice | Best Fit | Watch Point |
|---|---|---|
| Markdown/YAML in Git | Minimum viable catalog | Manual updates require discipline. |
| Homepage dashboard | User-facing links plus basic health | Dashboard is not the source of truth by itself. |
| NetBox/Nautobot | Network/service dependency modeling | More setup and schema decisions. |
| Backstage | Platform-style service catalog | Likely overkill until the lab behaves like a small platform. |
The Minimum Useful Record
A useful service entry has enough information to answer an outage question. What is broken? Who notices? Which host runs it? Which DNS name points to it? Which data path matters? Which backup restores it? Which account owns it?
If the entry cannot help during a restore, it is just a bookmark. The catalog should be useful when you are tired, traveling, or rebuilding from hardware failure.
Use stable service IDs rather than display names as the join point between catalog, monitoring, backup jobs, dashboards, and runbooks. Record relationships explicitly: service depends on database, DNS, identity, reverse proxy, storage, network, and power. A dependency should point to another catalog ID or a named external provider, not a sentence that automation cannot compare.
This is an illustrative local schema, not a record of a verified service or a tool import format. Set last_verified only after reconciling the actual runtime and recovery path. The example's backup label must resolve to records covering both the library and PostgreSQL at a coordinated recovery point; a PBS job name alone does not prove either is included. Resolve every dependency ID, including external database and storage services, in the real catalog.
id: photos
name: Family Photos
owner: primary-operator
users: household
route_ref: reverse-proxy/photos
runtime: docker-vm-01
data:
- /srv/photos/library
- postgres:photos
depends_on: [dns, reverse-proxy, oidc, nas-01]
backup: pbs-job-photos
restore_order: 30
monitor: https-check-photos
secret_ref: vault://homelab/photos
runbook: runbooks/photos.md
last_verified: nullThe catalog can contain sensitive infrastructure metadata even without passwords. Hostnames, addresses, external URLs, owner names, backup locations, and dependency graphs help an attacker. Restrict write access, keep Git history private when appropriate, encrypt offline copies, and use references such as vault:// rather than secrets or recovery codes.
Catalog vs Dashboard vs Wiki
A dashboard is a front door. A wiki is a place for notes. A catalog is the structured record that other views can consume. For a tiny lab they may be the same file, but keep the mental model separate.
- Catalog: service facts and dependencies.
- Dashboard: links and status for humans.
- Wiki/runbook: procedures and explanations.
- Monitoring: checks that prove services still behave.
Discovery Without Lying to Yourself
Homepage and other dashboards can discover Docker labels, and Backstage-style catalogs can use descriptor files. That is useful, but discovery sees what exists, not why it matters. Keep fields for restore priority, owner, backup method, and failure notes.
Recovery Handoff Pilot
Start with the five services whose failure someone would notice first. Ask a second person, using only an offline catalog export, to identify each service's host, URL, data, dependencies, backup, restore order, secret reference, and runbook. Then compare the records with running containers/VMs, DNS, proxy routes, monitoring, and backup jobs.
This article is documentation-backed; no original comparison of Homepage, NetBox, Nautobot, or Backstage was performed. The pilot measures record completeness and recovery usability, not product scale or automation quality. Choose the simplest implementation that passes the handoff and restore tests.
Implementation Details
Start with five services and a schema small enough to maintain. Reconcile each record with runtime, DNS, proxy, monitoring, and backup state, then ask a second person to use the offline export during a recovery exercise before adding more tooling.
- Create one catalog file with a row for every service people use.
- Add host, URL, DNS, port, data path, database, backup, and restore priority fields.
- Add a secret reference field that points to a vault item instead of storing the secret.
- Link each service to monitoring and backup status.
- Use the catalog during one controlled restore drill.
- Schedule a quarterly audit and remove abandoned services.
Evidence and Testing Methodology
- Coverage ratio for running services, DNS records, proxy routes, monitoring checks, and backup jobs against catalog records.
- Required-field completeness for owner, users, runtime, data, dependencies, backup, restore order, monitoring, secret reference, and runbook.
- A second-person handoff result: time and errors when locating and explaining five critical services without operator hints.
- An outage or restore drill showing whether the dependency graph and restore order led to the correct first action.
- An offline-readable encrypted export plus proof that the only catalog copy is not hosted on the infrastructure it documents.
Validation Checklist
- A second person can identify critical services and where they run.
- Every critical service has a backup location and restore note.
- The catalog is readable when DNS, reverse proxy, or the main server is down.
- Deprecated services are marked retired or removed.
- Dashboard links match the catalog records.
Maintenance Cadence
- Update a service record in the same change that adds, moves, exposes, renames, backs up, or retires the service.
- Monthly, reconcile automated discovery with the catalog and investigate orphan containers, DNS records, proxy routes, and monitors.
- Quarterly, review required fields, stale verification dates, retired services, secret references, and offline export readability.
- After every recovery drill, correct missing dependencies, ambiguous restore order, inaccessible runbooks, and fields that did not help.
Troubleshooting
| Symptom | Likely Cause | First Check |
|---|---|---|
| No one knows what broke | Services are documented by memory only | Open catalog and map user symptom to service, host, and dependency. |
| Restore misses data | Catalog did not record data path or database | Add storage and backup fields for every service. |
| Dashboard is stale | Links were maintained separately | Generate or review dashboard entries from the catalog. |
Common Mistakes
- Building a pretty dashboard with no backup or owner fields.
- Storing plaintext passwords in the catalog.
- Forgetting DNS, reverse proxy, and database dependencies.
- Letting dead containers stay in the inventory forever.
- Hosting the only copy on the broken server.
Useful Gear And Buyer Notes
A service catalog needs durable access more than specialized hardware. When buying recovery supplies, check label durability, encrypted-backup compatibility, safe fire rating, key support, server power and storage requirements, warranty, and replacement availability.
Affiliate disclosure: As an Amazon Associate, TechGeeks may earn from qualifying purchases. The product links below are buying references, not a requirement to buy a specific brand or seller. Verify compatibility, seller quality, warranty, and current specs before ordering.
- Amazon search: label maker network cables
- Amazon search: fireproof document safe
- Amazon search: NAS backup drive
- Amazon search: YubiKey security key
- Amazon search: mini PC server
Catalog Tooling Currency Check
This workflow was fact-checked on July 15, 2026 against current Homepage service and Docker configuration, Backstage software-catalog and descriptor documentation, and OpenTelemetry resource semantic conventions. The YAML example in this article is deliberately a small homelab schema, not a claim that those projects accept it unchanged or that one schema fits every inventory.
NIST Cybersecurity Framework 2.0 Asset Management outcome ID.AM-02 independently reinforces maintaining inventories of software, services, and systems. That baseline does not define a useful recovery catalog by itself: a homelab still needs owner, users, data, dependencies, backup, restore order, secret reference, and last-verified context.
When building automation around the catalog, validate parsing, required fields, unique IDs, resolved dependencies, secret detection, and offline export access. Test tool imports against that tool's own schema. Make a stale source visible in generated dashboards instead of silently presenting outdated recovery information.
Related TechGeeks Reading
- Docker Compose for Normal People
- Homelab Backup Strategy: NAS, Offsite Copies, and Restore Tests
- Remote Access Without Opening Router Ports
What This Evidence Does Not Prove
A complete row proves that fields were filled, not that they are correct, current, or sufficient for restore. Automated discovery proves that an object exists at scan time; it usually cannot infer business impact, data ownership, recovery priority, credentials, or why a dependency matters.
A dashboard reports links and perhaps health; it does not replace a catalog, monitoring, or a runbook. Git history improves auditability but can preserve deleted sensitive metadata. Backstage's catalog model demonstrates structured ownership at larger scale, but its documentation does not prove that operating Backstage is justified for a small lab.
Practical FAQ
Can I just use Homepage?
Yes for the first view, but add catalog fields somewhere. Links and icons are not enough for recovery.
Should this be in NetBox?
Use NetBox or Nautobot when IPs, devices, circuits, VLANs, and service dependencies need structured ownership.
How often should I update it?
Update it whenever a service is added, moved, exposed, backed up differently, or retired.
References
- https://gethomepage.dev/configs/services/
- https://gethomepage.dev/configs/docker/
- https://backstage.io/docs/features/software-catalog/
- https://backstage.io/docs/features/software-catalog/descriptor-format/
- https://backstage.io/docs/features/software-catalog/creating-the-catalog-graph/
- https://opentelemetry.io/docs/specs/semconv/resource/
- https://www.nist.gov/publications/nist-cybersecurity-framework-csf-20
- https://www.reddit.com/r/homelab/comments/1tpqoof/got_any_good_recommendations_for_keeping/
Final Thought
The catalog is working when it answers the question you ask during an outage: what is this, where is it, who needs it, and how do I bring it back?
