150 lines
4.9 KiB
Markdown
150 lines
4.9 KiB
Markdown
# 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
|