homelab-docs/README.md

Homelab Documentation

Documentation for Hutson's home infrastructure - two Proxmox servers running VMs and containers for home automation, media, development, and AI workloads.

🚀 Quick Start

New to this homelab? Start here:

1. CLAUDE.md - Quick reference guide for common tasks
2. SSH-ACCESS.md - How to connect to all systems
3. IP-ASSIGNMENTS.md - What's at what IP address
4. SERVICES.md - What services are running

Claude Code Session? Read CLAUDE.md first - it's your command center.

📚 Documentation Index

Infrastructure

Document	Description
GATEWAY.md	UniFi gateway monitoring, watchdog services, troubleshooting
VMS.md	Complete VM/LXC inventory, specs, GPU passthrough
HARDWARE.md	Server specs, GPUs, network cards, HBAs
STORAGE.md	ZFS pools, NFS/SMB shares, capacity planning
NETWORK.md	Bridges, VLANs, MTU config, Tailscale VPN
POWER-MANAGEMENT.md	CPU governors, GPU power states, optimizations
UPS.md	UPS configuration, NUT monitoring, power failure handling

Services & Applications

Document	Description
SERVICES.md	Complete service inventory with URLs and credentials
TRAEFIK.md	Reverse proxy setup, adding services, SSL certificates
HOMEASSISTANT.md	Home Assistant API, automations, integrations
PA-API.md	Personal Assistant API, MCP Bridge, Claude integration
SYNCTHING.md	File sync across all devices, API access, troubleshooting
SALTBOX.md	Media automation stack (Plex, *arr apps) (coming soon)

Access & Security

Document	Description
SSH-ACCESS.md	SSH keys, host aliases, password auth, QEMU agent
IP-ASSIGNMENTS.md	Complete IP address assignments for all devices
SECURITY.md	Firewall, access control, certificates (coming soon)

Operations

Document	Description
BACKUP-STRATEGY.md	🚨 Backup strategy, disaster recovery (CRITICAL)
MAINTENANCE.md	Regular procedures, update schedules, testing checklists
MONITORING.md	Health monitoring, alerts, dashboard recommendations
DISASTER-RECOVERY.md	Recovery procedures (coming soon)

Reference

Document	Description
EMC-ENCLOSURE.md	Storage enclosure SES commands, LCC troubleshooting
SHELL-ALIASES.md	ZSH aliases for Claude Code sessions

🖥️ System Overview

Servers

• PVE (10.10.10.120) - Primary Proxmox server

  • AMD Threadripper PRO 3975WX (32-core)
  • 128 GB RAM
  • NVIDIA Quadro P2000 + TITAN RTX

• PVE2 (10.10.10.102) - Secondary Proxmox server

  • AMD Threadripper PRO 3975WX (32-core)
  • 128 GB RAM
  • NVIDIA RTX A6000

Key Services

Service	Location	URL
Proxmox	PVE	https://pve.htsn.io
TrueNAS	VM 100	https://truenas.htsn.io
Plex	Saltbox VM	https://plex.htsn.io
Home Assistant	VM 110	https://homeassistant.htsn.io
Gitea	VM 300	https://git.htsn.io
PA API	docker-host2	https://pa.htsn.io (Tailscale)
Pi-hole	CT 200	http://10.10.10.10/admin
Traefik	CT 202	http://10.10.10.250:8080

See IP-ASSIGNMENTS.md for complete list

🔥 Emergency Procedures

Power Failure

1. UPS provides ~15 min runtime at typical load
2. At 2 min remaining, NUT triggers graceful VM shutdown
3. When power returns, servers auto-boot and start VMs in order

See UPS.md for details.

Service Down

# Quick health check (run from Mac Mini)
ssh pve 'qm list'                    # Check VMs on PVE
ssh pve2 'qm list'                   # Check VMs on PVE2
ssh pve 'pct list'                   # Check containers

# Syncthing status
curl -s -H "X-API-Key: oSQSrPnMnrEXuHqjWrRdrvq3TSXesAT5" \
  "http://127.0.0.1:8384/rest/system/connections"

# Restart a VM
ssh pve 'qm stop VMID && qm start VMID'

See CLAUDE.md for complete troubleshooting runbooks.

📞 Getting Help

Claude Code Assistant: Start a session in this directory - all context is available in CLAUDE.md

Key Contacts:

• Homelab Owner: Hutson
• Git Repo: https://git.htsn.io/hutson/homelab-docs
• Local Path: ~/Projects/homelab

🔄 Recent Changes

See CHANGELOG.md (coming soon) or the Changelog section in CLAUDE.md.

📝 Contributing

When updating docs:

1. Keep CLAUDE.md as quick reference only
2. Move detailed content to specialized docs
3. Update cross-references
4. Test all commands before committing
5. Add entries to changelog

cd ~/Projects/homelab
git add -A
git commit -m "Update documentation: <description>"
git push

---

Last Updated: 2026-01-02