History

nathan e16f98a183 feat(bootstrap)!: introduce unified bootstrap system with modular libraries

BREAKING CHANGE: day0bootstrap.sh deprecated in favor of bootstrap.sh

- Add scripts/bootstrap.sh (488 lines): Unified entrypoint supporting multiple hardware types (Proxmox/Docker VMs/Pi)
- Create scripts/lib/ modular library system:
  - detection.sh: OS/hardware/container detection (362 lines)
  - fingerprint.sh: System fingerprinting and inventory (494 lines)
  - network.sh: IP configuration and VLAN placement (356 lines)
  - proxmox.sh: PVE post-install automation (453 lines)
  - validation.sh: Comprehensive pre-flight checks (510 lines)
- Add validation tools: validate-node.sh, onboarding.sh, pi_init.sh
- Deprecate scripts/day0bootstrap.sh with graceful redirect wrapper
- Document architecture in scripts/README.md (495 lines) and PROXMOX-COMPARISON.md
- Update SOP-002 with new bootstrap workflow
- Add nodes/watchtower/compose.yaml (Raspberry Pi 5 stack)

Migration: Existing day0bootstrap.sh users automatically redirected to new system after 5-second warning. No manual intervention required.

Ref: Infrastructure automation modernization per active-tasks.md

2026-04-12 22:48:19 -04:00

KBAs

docs: reorganize documentation into KBAs/ and SOPs/ subdirectories

2026-04-11 23:56:43 -04:00

plans

feat(documentation): enhance migration guides for Git-crypt and prompt distribution

2026-04-12 01:31:32 -04:00

reports

docs: add Security Audit Report for Homelab infrastructure

2026-04-12 00:17:37 -04:00

SOPs

feat(bootstrap)!: introduce unified bootstrap system with modular libraries

2026-04-12 22:48:19 -04:00

README.md

feat(documentation): add SOP for initial infrastructure deployment with GitOps integration

2026-04-12 01:41:43 -04:00

TECHNICAL_RUNBOOK.md

Add technical runbook & handover documentation

2026-04-11 22:01:18 -04:00

README.md

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.

Infrastructure Deployment

SOP-002: Initial Infrastructure Deployment
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
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:

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

Last Updated: April 12, 2026