Build a Homelab Service Catalog Before You Forget Everything

A homelab service catalog is the record of what exists, why it exists, where it runs, how people reach it, where the data lives, and how it comes back after failure. A dashboard shows links; a catalog explains ownership, dependencies, backups, and recovery.

Catalog principle: Record enough structured context that another person can identify impact, dependencies, data, and restore order without opening the broken service or reading a plaintext secret.

The Short Version

• Start with a Markdown or YAML file in Git before installing a platform.
• Track dependencies, backup location, restore priority, monitoring, and secret location for each service.
• Never store plaintext secrets in the catalog; link to the password manager or vault item instead.

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.

Interactive reference model

Build a Homelab Service Catalog Before You Forget Everything reference model

Read the model left to right, then open each step below for the operational detail behind the diagram.

Plan Control Change Verify

01Record service+

Name, purpose, owner, users, URL, host, data path, and dependencies.

Output: document the evidence from this step before moving to the next one.

02Attach recovery+

Backup, restore order, runbook, and secret reference.

Output: document the evidence from this step before moving to the next one.

03Expose views+

Dashboard, wiki, monitoring, and alerts consume the catalog.

Output: document the evidence from this step before moving to the next one.

04Audit quarterly+

Remove dead services and fix missing recovery fields.

Output: document the evidence from this step before moving to the next one.

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.

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: 2026-07-15

The 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.

1. Create one catalog file with a row for every service people use.
2. Add host, URL, DNS, port, data path, database, backup, and restore priority fields.
3. Add a secret reference field that points to a vault item instead of storing the secret.
4. Link each service to monitoring and backup status.
5. Use the catalog during one controlled restore drill.
6. 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.

Before publication, validate the linked documentation, current field names, and any tool import claims. Recheck the published TechGeeks catalog before keeping internal links. If the example is expanded into automation, test parsing, required-field validation, duplicate IDs, secret detection, and an export that can be opened while the main server is unavailable. A generated dashboard should fail visibly when its source is stale rather than silently presenting old ownership or recovery data.

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?