hutson/homelab-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Complete Phase 2 documentation: Add HARDWARE, SERVICES, MONITORING, MAINTENANCE

Browse Source 
Phase 2 documentation implementation:
- Created HARDWARE.md: Complete hardware inventory (servers, GPUs, storage, network cards)
- Created SERVICES.md: Service inventory with URLs, credentials, health checks (25+ services)
- Created MONITORING.md: Health monitoring recommendations, alert setup, implementation plan
- Created MAINTENANCE.md: Regular procedures, update schedules, testing checklists
- Updated README.md: Added all Phase 2 documentation links
- Updated CLAUDE.md: Cleaned up to quick reference only (1340→377 lines)

All detailed content now in specialized documentation files with cross-references.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Hutson
2025-12-23 00:34:21 -05:00
parent 23e9df68c9
commit 56b82df497
14 changed files with 6328 additions and 1036 deletions
Download Patch File Download Diff File Expand all files Collapse all files

591
SERVICES.md Normal file
View File

@@ -0,0 +1,591 @@
# Services Inventory
Complete inventory of all services running across the homelab infrastructure.
## Overview
| Category | Services | Location | Access |
|----------|----------|----------|--------|
| **Infrastructure** | Proxmox, TrueNAS, Pi-hole, Traefik | VMs/CTs | Web UI + SSH |
| **Media** | Plex, *arr apps, downloaders | Saltbox VM | Web UI |
| **Development** | Gitea, Docker services | VMs | Web UI |
| **Home Automation** | Home Assistant, Happy Coder | VMs | Web UI + API |
| **Monitoring** | UPS (NUT), Syncthing, Pulse | Various | API |
**Total Services**: 25+ running services
---
## Service URLs Quick Reference
| Service | URL | Authentication | Purpose |
|---------|-----|----------------|---------|
| **Proxmox** | https://pve.htsn.io:8006 | Username + 2FA | VM management |
| **TrueNAS** | https://truenas.htsn.io | Username/password | NAS management |
| **Plex** | https://plex.htsn.io | Plex account | Media streaming |
| **Home Assistant** | https://homeassistant.htsn.io | Username/password | Home automation |
| **Gitea** | https://git.htsn.io | Username/password | Git repositories |
| **Excalidraw** | https://excalidraw.htsn.io | None (public) | Whiteboard |
| **Happy Coder** | https://happy.htsn.io | QR code auth | Remote Claude sessions |
| **Pi-hole** | http://10.10.10.10/admin | Password | DNS/ad blocking |
| **Traefik** | http://10.10.10.250:8080 | None (internal) | Reverse proxy dashboard |
| **Pulse** | https://pulse.htsn.io | Unknown | Monitoring dashboard |
| **Copyparty** | https://copyparty.htsn.io | Unknown | File sharing |
| **FindShyt** | https://findshyt.htsn.io | Unknown | Custom app |
---
## Infrastructure Services
### Proxmox VE (PVE & PVE2)
**Purpose**: Virtualization platform, VM/CT host
**Location**: Physical servers (10.10.10.120, 10.10.10.102)
**Access**: https://pve.htsn.io:8006, SSH
**Version**: Unknown (check: `pveversion`)
**Key Features**:
- Web-based management
- VM and LXC container support
- ZFS storage pools
- Clustering (2-node)
- API access
**Common Operations**:
```bash
# List VMs
ssh pve 'qm list'
# Create VM
ssh pve 'qm create VMID --name myvm ...'
# Backup VM
ssh pve 'vzdump VMID --dumpdir /var/lib/vz/dump'
```
**See**: [VMS.md](VMS.md)
---
### TrueNAS SCALE (VM 100)
**Purpose**: Central file storage, NFS/SMB shares
**Location**: VM on PVE (10.10.10.200)
**Access**: https://truenas.htsn.io, SSH
**Version**: TrueNAS SCALE (check version in UI)
**Key Features**:
- ZFS storage management
- NFS exports
- SMB shares
- Syncthing hub
- Snapshot management
**Storage Pools**:
- `vault`: Main data pool on EMC enclosure
**Shares** (needs documentation):
- NFS exports for Saltbox media
- SMB shares for Windows access
- Syncthing sync folders
**See**: [STORAGE.md](STORAGE.md)
---
### Pi-hole (CT 200)
**Purpose**: Network-wide DNS server and ad blocker
**Location**: LXC on PVE (10.10.10.10)
**Access**: http://10.10.10.10/admin
**Version**: Unknown
**Configuration**:
- **Upstream DNS**: Cloudflare (1.1.1.1)
- **Blocklists**: Unknown count
- **Queries**: All network DNS traffic
- **DHCP**: Disabled (router handles DHCP)
**Stats** (example):
```bash
ssh pihole 'pihole -c -e' # Stats
ssh pihole 'pihole status' # Status
```
**Common Tasks**:
- Update blocklists: `ssh pihole 'pihole -g'`
- Whitelist domain: `ssh pihole 'pihole -w example.com'`
- View logs: `ssh pihole 'pihole -t'`
---
### Traefik (CT 202)
**Purpose**: Reverse proxy for all public-facing services
**Location**: LXC on PVE (10.10.10.250)
**Access**: http://10.10.10.250:8080/dashboard/
**Version**: Unknown (check: `traefik version`)
**Managed Services**:
- All *.htsn.io domains (except Saltbox services)
- SSL/TLS certificates via Let's Encrypt
- HTTP → HTTPS redirects
**See**: [TRAEFIK.md](TRAEFIK.md) for complete configuration
---
## Media Services (Saltbox VM)
All media services run in Docker on the Saltbox VM (10.10.10.100).
### Plex Media Server
**Purpose**: Media streaming platform
**URL**: https://plex.htsn.io
**Access**: Plex account
**Features**:
- Hardware transcoding (TITAN RTX)
- Libraries: Movies, TV, Music
- Remote access enabled
- Managed by Saltbox
**Media Storage**:
- Source: TrueNAS NFS mounts
- Location: `/mnt/unionfs/`
**Common Tasks**:
```bash
# View Plex status
ssh saltbox 'docker logs -f plex'
# Restart Plex
ssh saltbox 'docker restart plex'
# Scan library
# (via Plex UI: Settings → Library → Scan)
```
---
### *arr Apps (Media Automation)
Running on Saltbox VM, managed via Traefik-Saltbox.
| Service | Purpose | URL | Notes |
|---------|---------|-----|-------|
| **Sonarr** | TV show automation | sonarr.htsn.io | Monitors, downloads, organizes TV |
| **Radarr** | Movie automation | radarr.htsn.io | Monitors, downloads, organizes movies |
| **Lidarr** | Music automation | lidarr.htsn.io | Monitors, downloads, organizes music |
| **Overseerr** | Request management | overseerr.htsn.io | User requests for media |
| **Bazarr** | Subtitle management | bazarr.htsn.io | Downloads subtitles |
**Downloaders**:
| Service | Purpose | URL |
|---------|---------|-----|
| **SABnzbd** | Usenet downloader | sabnzbd.htsn.io |
| **NZBGet** | Usenet downloader | nzbget.htsn.io |
| **qBittorrent** | Torrent client | qbittorrent.htsn.io |
**Indexers**:
| Service | Purpose | URL |
|---------|---------|-----|
| **Jackett** | Torrent indexer proxy | jackett.htsn.io |
| **NZBHydra2** | Usenet indexer proxy | nzbhydra2.htsn.io |
---
### Supporting Media Services
| Service | Purpose | URL |
|---------|---------|-----|
| **Tautulli** | Plex statistics | tautulli.htsn.io |
| **Organizr** | Service dashboard | organizr.htsn.io |
| **Authelia** | SSO authentication | auth.htsn.io |
---
## Development Services
### Gitea (VM 300)
**Purpose**: Self-hosted Git server
**Location**: VM on PVE2 (10.10.10.220)
**URL**: https://git.htsn.io
**Access**: Username/password
**Repositories**:
- homelab-docs (this documentation)
- Personal projects
- Private repos
**Common Tasks**:
```bash
# SSH to Gitea VM
ssh gitea-vm
# View logs
ssh gitea-vm 'journalctl -u gitea -f'
# Backup
ssh gitea-vm 'gitea dump -c /etc/gitea/app.ini'
```
**See**: Gitea documentation for API usage
---
### Docker Services (docker-host VM)
Running on VM 206 (10.10.10.206).
| Service | URL | Purpose | Port |
|---------|-----|---------|------|
| **Excalidraw** | https://excalidraw.htsn.io | Whiteboard/diagramming | 8080 |
| **Happy Server** | https://happy.htsn.io | Happy Coder relay | 3002 |
| **Pulse** | https://pulse.htsn.io | Monitoring dashboard | 7655 |
**Docker Compose files**: `/opt/{excalidraw,happy-server,pulse}/docker-compose.yml`
**Managing services**:
```bash
ssh docker-host 'docker ps'
ssh docker-host 'cd /opt/excalidraw && sudo docker-compose logs -f'
ssh docker-host 'cd /opt/excalidraw && sudo docker-compose restart'
```
---
## Home Automation
### Home Assistant (VM 110)
**Purpose**: Smart home automation platform
**Location**: VM on PVE (10.10.10.110)
**URL**: https://homeassistant.htsn.io
**Access**: Username/password
**Integrations**:
- UPS monitoring (NUT sensors)
- Unknown other integrations (needs documentation)
**Sensors**:
- `sensor.cyberpower_battery_charge`
- `sensor.cyberpower_load`
- `sensor.cyberpower_battery_runtime`
- `sensor.cyberpower_status`
**See**: [HOMEASSISTANT.md](HOMEASSISTANT.md)
---
### Happy Coder Relay (docker-host)
**Purpose**: Self-hosted relay server for Happy Coder mobile app
**Location**: docker-host (10.10.10.206)
**URL**: https://happy.htsn.io
**Access**: QR code authentication
**Stack**:
- Happy Server (Node.js)
- PostgreSQL (user/session data)
- Redis (real-time events)
- MinIO (file/image storage)
**Clients**:
- Mac Mini (Happy daemon)
- Mobile app (iOS/Android)
**Credentials**:
- Master Secret: `3ccbfd03a028d3c278da7d2cf36d99b94cd4b1fecabc49ab006e8e89bc7707ac`
- PostgreSQL: `happy` / `happypass`
- MinIO: `happyadmin` / `happyadmin123`
---
## File Sync & Storage
### Syncthing
**Purpose**: File synchronization across all devices
**Devices**:
- Mac Mini (10.10.10.125) - Hub
- MacBook - Mobile sync
- TrueNAS (10.10.10.200) - Central storage
- Windows PC (10.10.10.150) - Windows sync
- Phone (10.10.10.54) - Mobile sync
**API Keys**:
- Mac Mini: `oSQSrPnMnrEXuHqjWrRdrvq3TSXesAT5`
- MacBook: `qYkNdVLwy9qZZZ6MqnJr7tHX7KKdxGMJ`
- Phone: `Xxz3jDT4akUJe6psfwZsbZwG2LhfZuDM`
**Synced Folders**:
- documents (~11 GB)
- downloads (~38 GB)
- pictures
- notes
- desktop (~7.2 GB)
- config
- movies
**See**: [SYNCTHING.md](SYNCTHING.md)
---
### Copyparty (VM 201)
**Purpose**: Simple HTTP file sharing
**Location**: VM on PVE (10.10.10.201)
**URL**: https://copyparty.htsn.io
**Access**: Unknown
**Features**:
- Web-based file upload/download
- Lightweight
---
## Trading & AI Services
### AI Trading Platform (trading-vm)
**Purpose**: Algorithmic trading with AI models
**Location**: VM 301 on PVE2 (10.10.10.221)
**URL**: https://aitrade.htsn.io (if accessible)
**GPU**: RTX A6000 (48GB VRAM)
**Components**:
- Trading algorithms
- AI models for market prediction
- Real-time data feeds
- Backtesting infrastructure
**Access**: SSH only (no web UI documented)
---
### LM Dev (lmdev1)
**Purpose**: AI/LLM development environment
**Location**: VM 111 on PVE (10.10.10.111)
**URL**: https://lmdev.htsn.io (if accessible)
**GPU**: TITAN RTX (shared with Saltbox)
**Installed**:
- CUDA toolkit
- Python 3.11+
- PyTorch, TensorFlow
- Hugging Face transformers
---
## Monitoring & Utilities
### UPS Monitoring (NUT)
**Purpose**: Monitor UPS status and trigger shutdowns
**Location**: PVE (master), PVE2 (slave)
**Access**: Command-line (`upsc`)
**Key Commands**:
```bash
ssh pve 'upsc cyberpower@localhost'
ssh pve 'upsc cyberpower@localhost ups.load'
ssh pve 'upsc cyberpower@localhost battery.runtime'
```
**Home Assistant Integration**: UPS sensors exposed
**See**: [UPS.md](UPS.md)
---
### Pulse Monitoring
**Purpose**: Unknown monitoring dashboard
**Location**: docker-host (10.10.10.206:7655)
**URL**: https://pulse.htsn.io
**Access**: Unknown
**Needs documentation**:
- What does it monitor?
- How to configure?
- Authentication?
---
### Tailscale VPN
**Purpose**: Secure remote access to homelab
**Subnet Routers**:
- PVE (100.113.177.80) - Primary
- UCG-Fiber (100.94.246.32) - Failover
**Devices on Tailscale**:
- Mac Mini: 100.108.89.58
- PVE: 100.113.177.80
- TrueNAS: 100.100.94.71
- Pi-hole: 100.112.59.128
**See**: [NETWORK.md](NETWORK.md)
---
## Custom Applications
### FindShyt (CT 205)
**Purpose**: Unknown custom application
**Location**: LXC on PVE (10.10.10.8)
**URL**: https://findshyt.htsn.io
**Access**: Unknown
**Needs documentation**:
- What is this app?
- How to use it?
- Tech stack?
---
## Service Dependencies
### Critical Dependencies
```
TrueNAS
├── Plex (media files via NFS)
├── *arr apps (downloads via NFS)
├── Syncthing (central storage hub)
└── Backups (if configured)
Traefik (CT 202)
├── All *.htsn.io services
└── SSL certificate management
Pi-hole
└── DNS for entire network
Router
└── Gateway for all services
```
### Startup Order
**See [VMS.md](VMS.md)** for VM boot order configuration:
1. TrueNAS (storage first)
2. Saltbox (depends on TrueNAS NFS)
3. Other VMs
4. Containers
---
## Service Port Reference
### Well-Known Ports
| Port | Service | Protocol | Purpose |
|------|---------|----------|---------|
| 22 | SSH | TCP | Remote access |
| 53 | Pi-hole | UDP | DNS queries |
| 80 | Traefik | TCP | HTTP (redirects to 443) |
| 443 | Traefik | TCP | HTTPS |
| 3000 | Gitea | TCP | Git HTTP/S |
| 8006 | Proxmox | TCP | Web UI |
| 8096 | Plex | TCP | Plex Media Server |
| 8384 | Syncthing | TCP | Web UI |
| 22000 | Syncthing | TCP | Sync protocol |
### Internal Ports
| Port | Service | Purpose |
|------|---------|---------|
| 3002 | Happy Server | Relay backend |
| 5432 | PostgreSQL | Happy Server DB |
| 6379 | Redis | Happy Server cache |
| 7655 | Pulse | Monitoring |
| 8080 | Excalidraw | Whiteboard |
| 8080 | Traefik | Dashboard |
| 9000 | MinIO | Object storage |
---
## Service Health Checks
### Quick Health Check Script
```bash
#!/bin/bash
# Check all critical services
echo "=== Infrastructure ==="
curl -Is https://pve.htsn.io:8006 | head -1
curl -Is https://truenas.htsn.io | head -1
curl -I http://10.10.10.10/admin 2>/dev/null | head -1
echo ""
echo "=== Media Services ==="
curl -Is https://plex.htsn.io | head -1
curl -Is https://sonarr.htsn.io | head -1
curl -Is https://radarr.htsn.io | head -1
echo ""
echo "=== Development ==="
curl -Is https://git.htsn.io | head -1
curl -Is https://excalidraw.htsn.io | head -1
echo ""
echo "=== Home Automation ==="
curl -Is https://homeassistant.htsn.io | head -1
curl -Is https://happy.htsn.io/health | head -1
```
### Service-Specific Checks
```bash
# Proxmox VMs
ssh pve 'qm list | grep running'
# Docker services
ssh docker-host 'docker ps --format "{{.Names}}: {{.Status}}"'
# Syncthing
curl -H "X-API-Key: oSQSrPnMnrEXuHqjWrRdrvq3TSXesAT5" \
"http://127.0.0.1:8384/rest/system/status"
# UPS
ssh pve 'upsc cyberpower@localhost ups.status'
```
---
## Service Credentials
**Location**: See individual service documentation
| Service | Credentials Location | Notes |
|---------|---------------------|-------|
| Proxmox | Proxmox UI | Username + 2FA |
| TrueNAS | TrueNAS UI | Root password |
| Plex | Plex account | Managed externally |
| Gitea | Gitea DB | Self-managed |
| Pi-hole | `/etc/pihole/setupVars.conf` | Admin password |
| Happy Server | [CLAUDE.md](CLAUDE.md) | Master secret, DB passwords |
**⚠️ Security Note**: Never commit credentials to Git. Use proper secrets management.
---
## Related Documentation
- [VMS.md](VMS.md) - VM/service locations
- [TRAEFIK.md](TRAEFIK.md) - Reverse proxy config
- [IP-ASSIGNMENTS.md](IP-ASSIGNMENTS.md) - Service IP addresses
- [NETWORK.md](NETWORK.md) - Network configuration
- [MONITORING.md](MONITORING.md) - Monitoring setup (coming soon)
---
**Last Updated**: 2025-12-22
**Status**: ⚠️ Incomplete - many services need documentation (passwords, features, usage)