Skip to content

Homelab Standards & Control Plane Enforcement

This section documents the standards that govern all infrastructure changes across the homelab (charliehub, px1, px2, px3, px5).

Why Standards Matter

A unified homelab requires consistent patterns to prevent chaos:

  • Single Source of Truth: Changes come from one place, not scattered across files
  • Drift Prevention: Configuration stays consistent, no shadow configurations
  • Auditability: All changes are traceable and reversible
  • Scalability: Patterns work across all nodes, not node-specific hacks
  • Safety: Constraints prevent invalid states before they happen

The 10 Commandments

All nodes in the homelab follow these non-negotiable rules:

  1. PostgreSQL/Database tables are the source of truth (not YAML, not Docker labels)
  2. All changes go through the API (not direct SQL, not manual edits)
  3. NEVER edit generated/output files directly
  4. NEVER create manual configuration files (temporary or otherwise)
  5. NEVER use Docker labels (providers are disabled)
  6. NEVER bypass the validation layer (constraints exist for a reason)
  7. Extend the API, don't bypass it (if API can't express it, extend it)
  8. Output files are read-only artifacts (treat them as generated, not authored)
  9. No shadow configurations (no temporary routes, no workarounds)
  10. When unsure: STOP and propose an extension (don't bypass, extend)

Scope

These standards apply to:

  • ✅ charliehub: Control plane, routing, domain management
  • ✅ px1, px2, px3, px5: Any configuration managed via databases/APIs
  • ✅ All future nodes: Automatically inherit these standards

Questions?

If you have a routing change, configuration addition, or feature request:

  1. Check if the API supports it → Use the API
  2. If API can't express it → Propose an extension to the API
  3. Never bypass the API with manual edits

The API is designed to grow. Extend it, don't bypass it.