kavren
e0a64b1b92
- Document OPNsense WAN configuration (pm4 vmbr1 with USB NIC) - Add DHCP-based isolation workaround for unmanaged Gigabyte switches - Plan subnet scheme: LAN (10.4.2.0/24), IoT (10.4.10.0/24), Guest (10.4.20.0/24) - Document planned OPNsense firewall rules for isolation - Update tasks with OPNsense migration and isolation steps - Fix Claude Code hooks settings (remove matcher from Stop hook) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
146 lines
4.4 KiB
Markdown
146 lines
4.4 KiB
Markdown
# Documentation Index
|
|
|
|
> **Last Updated**: 2025-12-21 (OPNsense WAN config, DHCP isolation strategy)
|
|
> **IMPORTANT**: Update this index whenever you modify documentation files
|
|
|
|
## Quick Reference
|
|
|
|
Need to know... | Check this file
|
|
--- | ---
|
|
Node IPs, service locations, storage paths | `INFRASTRUCTURE.md`
|
|
Service configs, API keys, copy/paste configs | `CONFIGURATIONS.md`
|
|
Why we made a decision, common patterns | `DECISIONS.md`
|
|
What's currently being worked on | `TASKS.md`
|
|
Recent changes and when they happened | `CHANGELOG.md`
|
|
|
|
## Core Documentation Files
|
|
|
|
### INFRASTRUCTURE.md
|
|
**Purpose**: Single source of truth for all infrastructure
|
|
**Contains**:
|
|
- Cluster node IPs and specs
|
|
- Complete service map with IPs, ports, domains
|
|
- Storage architecture (NFS mounts, local storage, ZFS)
|
|
- Network configuration
|
|
- Important file paths
|
|
|
|
**Update when**: Infrastructure changes (new service, IP change, storage mount)
|
|
|
|
---
|
|
|
|
### CONFIGURATIONS.md
|
|
**Purpose**: Detailed service configurations
|
|
**Contains**:
|
|
- Traefik SSL/TLS setup
|
|
- Service routing examples
|
|
- API keys and credentials
|
|
- Copy/paste ready config snippets
|
|
- Service-specific settings
|
|
|
|
**Update when**: Service configuration changes, API keys rotate, new services added
|
|
|
|
---
|
|
|
|
### DECISIONS.md
|
|
**Purpose**: Architecture decisions and patterns
|
|
**Contains**:
|
|
- Why we chose LXC vs Docker for services
|
|
- Authentication strategy
|
|
- File permission standards (777 for media)
|
|
- Common troubleshooting patterns
|
|
- Known issues and workarounds
|
|
|
|
**Update when**: Making architectural decisions, discovering new patterns, solving recurring issues
|
|
|
|
---
|
|
|
|
### TASKS.md
|
|
**Purpose**: Track ongoing work and TODO items
|
|
**Contains**:
|
|
- Active tasks being worked on
|
|
- Pending tasks
|
|
- Blocked items
|
|
- Task priority
|
|
|
|
**Update when**: Starting new work, completing tasks, discovering new work
|
|
|
|
---
|
|
|
|
### CHANGELOG.md
|
|
**Purpose**: Historical record of changes
|
|
**Contains**:
|
|
- Date-stamped entries for all significant changes
|
|
- Who made the change (user/Claude)
|
|
- What was changed and why
|
|
- Links to relevant commits or files
|
|
|
|
**Update when**: After completing any significant work
|
|
|
|
---
|
|
|
|
## Legacy Files (To Be Removed)
|
|
|
|
These files will be consolidated into the core docs above:
|
|
|
|
- ~~`infrastructure-map.md`~~ → Merged into `INFRASTRUCTURE.md`
|
|
- ~~`home-assistant-traefik.md`~~ → Merged into `CONFIGURATIONS.md`
|
|
- ~~`traefik-ssl-setup.md`~~ → Merged into `CONFIGURATIONS.md`
|
|
- ~~`recyclarr-setup.md`~~ → Merged into `CONFIGURATIONS.md`
|
|
|
|
Keep for reference (detailed info):
|
|
- `cluster-state.md` - Detailed cluster topology
|
|
- `inventory.md` - Complete VM/LXC inventory
|
|
- `network.md` - Detailed network info
|
|
- `storage.md` - Detailed storage info
|
|
- `services.md` - Service dependencies and details
|
|
|
|
## Documentation Workflow
|
|
|
|
### When Making Changes
|
|
|
|
1. **Before starting**: Check `INFRASTRUCTURE.md` for current state
|
|
2. **During work**: Note what you're changing
|
|
3. **After completing**:
|
|
- Update relevant core doc (`INFRASTRUCTURE.md`, `CONFIGURATIONS.md`, or `DECISIONS.md`)
|
|
- Add entry to `CHANGELOG.md` with date and description
|
|
- Update `TASKS.md` to mark work complete
|
|
- Update `README.md` (this file) Last Updated date
|
|
|
|
### Example Workflow
|
|
|
|
```
|
|
Task: Add new service "Tautulli" to monitor Jellyfin
|
|
|
|
1. Check INFRASTRUCTURE.md → Find next available IP
|
|
2. Deploy service
|
|
3. Update INFRASTRUCTURE.md → Add Tautulli to service map
|
|
4. Update CONFIGURATIONS.md → Add Tautulli config snippet
|
|
5. Update CHANGELOG.md → "2025-11-17: Added Tautulli LXC..."
|
|
6. Update TASKS.md → Mark "Deploy Tautulli" as complete
|
|
7. Update README.md → Change Last Updated date
|
|
```
|
|
|
|
## File Organization
|
|
|
|
```
|
|
docs/
|
|
├── README.md ← You are here (index and guide)
|
|
├── INFRASTRUCTURE.md ← Infrastructure reference
|
|
├── CONFIGURATIONS.md ← Service configurations
|
|
├── DECISIONS.md ← Architecture decisions
|
|
├── TASKS.md ← Current/ongoing tasks
|
|
├── CHANGELOG.md ← Historical changes
|
|
├── cluster-state.md ← [Keep] Detailed topology
|
|
├── inventory.md ← [Keep] Full VM/LXC list
|
|
├── network.md ← [Keep] Network details
|
|
├── storage.md ← [Keep] Storage details
|
|
└── services.md ← [Keep] Service details
|
|
```
|
|
|
|
## Maintenance
|
|
|
|
- Review and update docs weekly
|
|
- Clean up completed tasks monthly
|
|
- Archive old changelog entries yearly
|
|
- Verify INFRASTRUCTURE.md matches reality regularly
|