homelab/documentation

Documentation

Overview

This directory contains all technical documentation for the Castaldi Family Homelab infrastructure.

---

Quick Reference

📘 Runbooks & Guides

• TECHNICAL_RUNBOOK.md - Complete infrastructure reference, emergency procedures, and maintenance schedule
• SECURITY_AUDIT_REPORT.md - 🔴 Security audit findings, exposed credentials, and remediation steps

---

Knowledge Base Articles (KBAs/)

Structured troubleshooting articles following the incident → resolution format.

GitOps & Deployment

• KBA-001: Komodo GitOps Stack Deployment Failures
  Troubleshooting guide for Git-linked stack pull/deploy failures, canonicalize errors, and Docker image tag issues.

---

Standard Operating Procedures (SOPs/)

Step-by-step guides for operational tasks and migrations.

Stack Management

• SOP-001: Migrate Stack from UI to Git
  Complete guide for converting Komodo stacks from UI-defined to Git-based deployment, including secrets management and verification steps.

---

Document Conventions

• KBA-XXX: Troubleshooting articles with clear problem/solution format (stored in KBAs/)
• SOP-XXX: Procedural guides for operational tasks (stored in SOPs/)
• Runbooks: Infrastructure reference and emergency procedures (root level)

---

Contributing

When documenting new issues or procedures:

1. KBAs: Create in KBAs/ folder for troubleshooting scenarios with clear diagnosis → resolution
2. SOPs: Create in SOPs/ folder for repeatable operational procedures and migrations
3. Update Runbook: Add new emergency procedures to TECHNICAL_RUNBOOK.md
4. Update Repository Memory: Store critical lessons in /memories/repo/
5. Commit Messages: Use conventional commits (e.g., docs(kba): add KBA-002 for...)

---

Last Updated: April 12, 2026