Initial infrastructure documentation - comprehensive homelab reference

2026-02-23 03:42:22 +00:00
commit 0682c79580
169 changed files with 63913 additions and 0 deletions
--- a/infrastructure/README.md
+++ b/infrastructure/README.md
@@ -0,0 +1,174 @@
+# Home Infrastructure
+
+Comprehensive documentation and configuration management for home network infrastructure, Home Assistant, and smart home automation.
+
+## Repository Structure
+
+```
+infrastructure/
+├── home-assistant/          # Home Assistant configuration files
+│   ├── configuration.yaml
+│   ├── automations.yaml
+│   ├── scripts.yaml
+│   ├── switches.yaml
+│   └── secrets.yaml (gitignored)
+│
+├── esphome/                 # ESPHome device configurations
+│   ├── garage-controller.yaml
+│   └── README.md
+│
+├── voice-assistant/         # Local voice assistant system
+│   ├── gaming-pc-setup/          # Docker services (GPU-accelerated AI)
+│   ├── surface-go-setup/         # Wyoming satellite installation
+│   ├── home-assistant-config/    # Voice pipeline HA config (merge with main)
+│   ├── docs/                     # Voice system documentation
+│   ├── README.md                 # Voice system overview
+│   └── QUICK_START.md           # 30-minute voice setup guide
+│
+├── docs/                    # Infrastructure documentation
+│   ├── FURNACE-PROJECT.md            # Furnace control integration project
+│   ├── HOME-ASSISTANT-CONFIG-MERGE.md # Guide to merge voice HA config
+│   ├── MQTT-SETUP.md                 # MQTT broker configuration
+│   ├── DNS-OVER-TLS-SETUP.md         # DNS security setup
+│   ├── MONITORING.md                 # System monitoring setup
+│   ├── SERVICES.md                   # Services inventory
+│   ├── DISASTER-RECOVERY.md          # Backup and recovery procedures
+│   ├── RUNBOOK.md                    # Operational procedures
+│   └── IMPROVEMENTS.md               # Future improvements tracking
+│
+├── scripts/                 # Automation and utility scripts
+│
+└── claude-shared/          # Shared resources with Claude Code assistant
+```
+
+## Quick Start
+
+### Home Assistant
+Configuration files are in `/home-assistant/`.
+
+**Key Files:**
+- `configuration.yaml` - Main HA configuration
+- `automations.yaml` - All automations
+- `scripts.yaml` - Reusable scripts
+- `secrets.yaml` - Sensitive data (create from secrets.yaml.example)
+
+**Deployment:**
+Copy files to your Home Assistant config directory (typically `/config/` in HA OS).
+
+### ESPHome Devices
+Device configurations are in `/esphome/`.
+
+**Current Devices:**
+- **garage-controller** - ESP32 with 8-relay board controlling garage doors, lights, and planned furnace integration
+
+**Deployment:**
+```bash
+cd esphome
+esphome run garage-controller.yaml
+```
+
+Or use Home Assistant ESPHome integration for OTA updates.
+
+### Voice Assistant
+
+**Local GPU-accelerated voice assistant system** with Home Assistant integration.
+
+**System Components:**
+- **Gaming PC (RTX 5060):** Docker containers for Ollama LLM, Whisper STT, Piper TTS, OpenWakeWord
+- **Home Assistant:** Voice pipeline coordinator
+- **Surface Go:** Wyoming satellite (microphone/speaker interface)
+
+**Quick Start:**
+1. Set up Gaming PC AI services: `/voice-assistant/gaming-pc-setup/`
+2. Set up Surface Go satellite: `/voice-assistant/surface-go-setup/`
+3. Merge voice HA config: See `/docs/HOME-ASSISTANT-CONFIG-MERGE.md`
+4. Full documentation: `/voice-assistant/README.md`
+
+**Current Status:** Operational - needs HA config merge for full integration
+
+## Active Projects
+
+### 🔥 Furnace Control Integration
+- **Status:** Planning phase
+- **Goal:** Replace failed furnace board with ESP32-based smart control
+- **Documentation:** [docs/FURNACE-PROJECT.md](docs/FURNACE-PROJECT.md)
+- **Hardware:** ESP32-WROOM-32E with relay board, 6x temp/humidity sensors
+- **Features:** Multi-zone monitoring (garage + shed), HA integration, safety interlocks
+
+### 🎤 Local Voice Assistant
+- **Status:** Operational, pending HA config merge
+- **Goal:** GPU-accelerated local voice control with LLM
+- **Documentation:** [voice-assistant/README.md](voice-assistant/README.md)
+- **Hardware:** Gaming PC (RTX 5060), Surface Go (Wyoming satellite)
+- **Features:** Ollama LLM, Whisper STT, Piper TTS, OpenWakeWord, no cloud dependencies
+- **Integration:** See [docs/HOME-ASSISTANT-CONFIG-MERGE.md](docs/HOME-ASSISTANT-CONFIG-MERGE.md)
+
+### 🌐 Network Infrastructure
+- **MQTT:** Mosquitto broker for device communication
+- **DNS:** DNS-over-TLS with Unbound
+- **Documentation:** See docs/MQTT-SETUP.md and docs/DNS-OVER-TLS-SETUP.md
+
+## Documentation
+
+All infrastructure documentation is in the `/docs/` directory:
+
+- **[FURNACE-PROJECT.md](docs/FURNACE-PROJECT.md)** - ESP32 furnace control integration
+- **[HOME-ASSISTANT-CONFIG-MERGE.md](docs/HOME-ASSISTANT-CONFIG-MERGE.md)** - Merge voice assistant HA config
+- **[MQTT-SETUP.md](docs/MQTT-SETUP.md)** - MQTT broker setup and configuration
+- **[DNS-OVER-TLS-SETUP.md](docs/DNS-OVER-TLS-SETUP.md)** - Secure DNS configuration
+- **[MONITORING.md](docs/MONITORING.md)** - System monitoring and alerting
+- **[SERVICES.md](docs/SERVICES.md)** - Inventory of all services
+- **[DISASTER-RECOVERY.md](docs/DISASTER-RECOVERY.md)** - Backup and recovery procedures
+- **[RUNBOOK.md](docs/RUNBOOK.md)** - Operational procedures and troubleshooting
+
+**Voice assistant documentation** is in `/voice-assistant/docs/`:
+- Installation, commands, calendar setup, troubleshooting
+
+## Network Information
+
+Current network setup and IP allocations are documented in:
+- [IP-ALLOCATION.md](IP-ALLOCATION.md) - IP address assignments
+- DHCP exports in repository root
+
+## Contributing
+
+This is a personal infrastructure repository. Updates are made through:
+1. Local testing and validation
+2. Git commits with descriptive messages
+3. Push to GitHub for backup and history
+
+## Secrets Management
+
+Sensitive information (passwords, API keys, etc.) is stored in `secrets.yaml` files which are gitignored.
+
+**Template files:**
+- `/home-assistant/secrets.yaml.example`
+- Create your own `secrets.yaml` from the template
+
+## Backup Strategy
+
+See [DISASTER-RECOVERY.md](docs/DISASTER-RECOVERY.md) for:
+- Backup procedures
+- Recovery steps
+- Critical system information
+
+## Support & Notes
+
+- **Experience Level:** 20+ years low voltage wiring, network infrastructure
+- **Tools:** Home Assistant, ESPHome, MQTT, Unbound DNS
+- **Approach:** Document everything, safety-first, incremental improvements
+
+## Recent Updates
+
+- **2025-11-28:**
+  - Consolidated all smart home projects into monorepo
+  - Added ESPHome directory and furnace control project documentation
+  - Integrated voice assistant project (Gaming PC AI + Surface Go)
+  - Created Home Assistant config merge guide
+- **2025-11-27:** Home Assistant configuration updates
+- **2025-11-18:** MQTT and DNS-over-TLS setup documentation
+
+---
+
+*Maintained by: Fred N9MRQ*
+*Repository: https://github.com/FredN9MRQ/infrastructure*