homelab-docs/infrastructure/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Quick Reference

This is an infrastructure documentation and automation repository for a self-hosted home lab environment.

When you need specific information, refer to these specialized docs:

Core Architecture

• .claude/docs/ARCHITECTURE.md - Infrastructure components, network config, WireGuard VPN
• .claude/docs/SERVICES.md - Deployed services, planned deployments, service-specific details
• .claude/docs/IP-QUICK-REF.md - Essential IP addresses (< 20 most-used IPs)

Workflows & Operations

• .claude/docs/COMMON-TASKS.md - SSH access, Caddy management, git workflow, script deployment
• .claude/docs/HOME-ASSISTANT.md - HA config management, sync workflows, integrations
• .claude/docs/CERTIFICATES.md - Step-CA setup, ACME provisioner, SSL configuration

Detailed References (load when needed)

• IP-ALLOCATION.md - Complete network IP allocation (10.0.10.0/24) - SOURCE OF TRUTH
• infrastructure-audit.md - Current infrastructure state, running containers, service details
• SERVICES.md - Comprehensive service documentation with startup/health check commands
• RUNBOOK.md - Operational procedures
• scripts/README.md - Script usage and automation
• guides/HOMELAB-BACKUP-STRATEGY.md - Backup system architecture

Essential Quick Facts

Primary Infrastructure:

• VPS: fred@66.63.182.168 (Caddy reverse proxy)
• Gaming VPS: ubuntu@51.222.12.162 (WireGuard server, deadeyeg4ming.vip)
• Proxmox: root@10.0.10.3 (main-pve), root@10.0.10.2 (pve-router), root@10.0.10.4 (pve-storage)
• Network: 10.0.10.0/24 (DHCP: .50-.254, Static: .1-.49)

Critical IPs:

• 10.0.10.1 - UCG Ultra (gateway)
• 10.0.10.3 - main-pve (primary Proxmox)
• 10.0.10.10 - HOMELAB-COMMAND (Gaming PC, Windows 11, Claude Code host)
• 10.0.10.24 - Home Assistant

WireGuard Tunnel:

• Tunnel: 10.0.9.0/24 (Gaming VPS .1, UCG Ultra .2, VPS proxy IP .3)
• Endpoint: 51.222.12.162:51820

Documentation Structure

Living Docs: infrastructure-audit.md, IP-ALLOCATION.md, IMPROVEMENTS.md, MORNING-REMINDER.md

Reference Guides: BRAINSTORM.md, RUNBOOK.md, DISASTER-RECOVERY.md, MONITORING.md

Automation: scripts/README.md (all scripts require customization, use --dry-run)

Key Constraints

• VPS: 2 CPU / 4GB RAM - lightweight services only
• Proxmox storage: local only (never local-lvm)
• SSH: Always use key-based auth
• Scripts: Test with --dry-run before production

Important Service Patterns

Internal HTTPS Access (Caddy Internal Proxy)

Services on CT 127 (Dockge) use Caddy Internal Proxy for HTTPS with self-signed certificates:

• Location: CT 127 (10.0.10.27)
• Config: /opt/caddy-internal/Caddyfile
• Reload: ssh root@10.0.10.3 "pct exec 127 -- docker exec caddy-internal caddy reload --config /etc/caddy/Caddyfile"
• CA Certificate: Extract with pct exec 127 -- docker exec caddy-internal cat /data/caddy/pki/authorities/local/root.crt

Internal domains pattern: https://<service>.nianticbooks.home → 10.0.10.27:<port>

To enable HTTPS access:

1. Extract CA cert from Caddy Internal
2. Install on client devices (Windows: Trusted Root Certification Authorities)
3. Add entries to C:\Windows\System32\drivers\etc\hosts pointing to 10.0.10.27

TODO: Dockge container (CT 127) is not configured with the internal CA certificate. This needs to be addressed to allow Dockge UI to trust internal services using Caddy Internal PKI certificates.

Public HTTPS Access (via VPS Caddy)

Services exposed publicly use Caddy on VPS (66.63.182.168):

• Config: /etc/caddy/Caddyfile on VPS
• Reload: ssh fred@66.63.182.168 "sudo systemctl reload caddy"
• Certificates: Automatic Let's Encrypt via ACME
• Traffic Flow: Internet → VPS Caddy → WireGuard tunnel (10.0.9.3) → Gaming VPS (10.0.9.1) → Home network (10.0.10.x)

Current routing limitation: WireGuard tunnel between Gaming VPS and home network has routing issues. Services work through port forwarding (DNAT) but general HTTP proxying times out. For new services requiring public access, prefer internal-only setup until routing is fixed.

LXC Container Management

Execute commands in containers:

ssh root@10.0.10.3 "pct exec <CT-ID> -- <command>"

Common container IDs:

• CT 127 (Dockge): Media stack, internal proxy, Docker Compose management
• CT 106 (n8n): Workflow automation
• CT 102 (PostgreSQL): Shared database
• CT 121 (Authentik): SSO/authentication
• CT 128 (Uptime Kuma): Monitoring

Docker in LXC: Dockge (CT 127) runs Docker. Access containers:

pct exec 127 -- docker ps
pct exec 127 -- docker logs <container-name>
pct exec 127 -- docker restart <container-name>

Network Troubleshooting

WireGuard Tunnel Status

Gaming VPS acts as hub:

• 10.0.9.1 (Gaming VPS server)
• 10.0.9.2 (UCG Ultra client - gateway to home network)
• 10.0.9.3 (Old VPS proxy IP)

Check tunnel:

# From Gaming VPS
ssh ubuntu@51.222.12.162 "sudo wg show"

# From old VPS
ssh fred@66.63.182.168 "sudo wg show"

Known issue: Gaming VPS cannot currently route traffic between WireGuard peers (10.0.9.3 → home network 10.0.10.x). Handshakes work but ICMP/HTTP traffic times out. UCG Ultra firewall allows traffic; issue is likely routing configuration on Gaming VPS.

DNS Resolution for Internal Services

Internal .home domains require hosts file entries:

• Windows: C:\Windows\System32\drivers\etc\hosts
• Linux/Mac: /etc/hosts

Format: 10.0.10.27 <service>.nianticbooks.home

Documentation Maintenance

Living documents (update frequently):

• IP-ALLOCATION.md - Network IP assignments (source of truth)
• infrastructure-audit.md - Current infrastructure state
• IMPROVEMENTS.md - Planned enhancements
• MORNING-REMINDER.md - Daily workflow checklist

When adding new services:

1. Reserve IP in IP-ALLOCATION.md
2. Document in SERVICES.md with startup/health check commands
3. Update infrastructure-audit.md with deployment date
4. Add to relevant .claude/docs files
5. If using internal HTTPS: add to Caddy Internal config
6. If using public HTTPS: add to VPS Caddy config