proxmox-infra/docs/README.md

Documentation Index

Last Updated: 2025-12-21 (OPNsense VLANs, firewall rules, network isolation) 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