66 lines
2.3 KiB
Markdown
66 lines
2.3 KiB
Markdown
# Documentation
|
|
|
|
## Overview
|
|
|
|
This directory contains all technical documentation for the Castaldi Family Homelab infrastructure.
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
### 📘 Runbooks & Guides
|
|
|
|
- **[TECHNICAL_RUNBOOK.md](TECHNICAL_RUNBOOK.md)** - Complete infrastructure reference, emergency procedures, and maintenance schedule
|
|
- **[SECURITY_AUDIT_REPORT.md](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](KBAs/KBA-001-Komodo-GitOps-Stack-Deployment-Failures.md)**
|
|
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.
|
|
|
|
### Infrastructure Deployment
|
|
|
|
- **[SOP-002: Initial Infrastructure Deployment](SOPs/SOP-002-Initial-Infrastructure-Deployment.md)**
|
|
Complete guide for deploying the homelab from scratch, including secure repository setup, Ansible control node configuration, core service deployment, and GitOps integration.
|
|
|
|
### Stack Management
|
|
|
|
- **[SOP-001: Migrate Stack from UI to Git](SOPs/SOP-001-Migrate-Stack-from-UI-to-Git.md)**
|
|
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
|