# 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](CLAUDE.md) - Quick reference guide for common tasks
2. [SSH-ACCESS.md](SSH-ACCESS.md) - How to connect to all systems
3. [IP-ASSIGNMENTS.md](IP-ASSIGNMENTS.md) - What's at what IP address
4. [SERVICES.md](SERVICES.md) - What services are running

**Claude Code Session?** Read [CLAUDE.md](CLAUDE.md) first - it's your command center.

## 📚 Documentation Index

### Infrastructure

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

### Services & Applications

| Document | Description |
|----------|-------------|
| [SERVICES.md](SERVICES.md) | Complete service inventory with URLs and credentials |
| [TRAEFIK.md](TRAEFIK.md) | Reverse proxy setup, adding services, SSL certificates |
| [HOMEASSISTANT.md](HOMEASSISTANT.md) | Home Assistant API, automations, integrations |
| [SYNCTHING.md](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-ACCESS.md) | SSH keys, host aliases, password auth, QEMU agent |
| [IP-ASSIGNMENTS.md](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.md) | 🚨 Backup strategy, disaster recovery (CRITICAL) |
| [MAINTENANCE.md](MAINTENANCE.md) | Regular procedures, update schedules, testing checklists |
| [MONITORING.md](MONITORING.md) | Health monitoring, alerts, dashboard recommendations |
| [DISASTER-RECOVERY.md](#) | Recovery procedures (coming soon) |

### Reference

| Document | Description |
|----------|-------------|
| [EMC-ENCLOSURE.md](EMC-ENCLOSURE.md) | Storage enclosure SES commands, LCC troubleshooting |
| [SHELL-ALIASES.md](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 |
| **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](IP-ASSIGNMENTS.md)

## 🔥 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](UPS.md) for details.

### Service Down

```bash
# 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](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](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

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

---

**Last Updated**: 2026-01-02