nathan
a23a8581ee
- documentation/KBAs/: Created subdirectory for Knowledge Base Articles - documentation/SOPs/: Created subdirectory for Standard Operating Procedures - documentation/README.md: Updated to reflect new structure with section descriptions - Moved KBA-001 to KBAs/ folder - Created SOP-001 (Migrate Stack from UI to Git) in SOPs/ folder - Fixed all cross-reference links to use correct relative paths (../) Improves documentation organization by separating troubleshooting guides (KBAs) from procedural guides (SOPs), making it easier to navigate and maintain the knowledge base as it grows.
61 lines
2.0 KiB
Markdown
61 lines
2.0 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
|
|
- **[LLM_HANDOVER.md](LLM_HANDOVER.md)** - Quick-start context document for AI-assisted troubleshooting sessions
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
### 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 11, 2026
|