163 lines
6.5 KiB
Markdown
163 lines
6.5 KiB
Markdown
# 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](.claude/docs/ARCHITECTURE.md) - Infrastructure components, network config, WireGuard VPN
|
|
- [.claude/docs/SERVICES.md](.claude/docs/SERVICES.md) - Deployed services, planned deployments, service-specific details
|
|
- [.claude/docs/IP-QUICK-REF.md](.claude/docs/IP-QUICK-REF.md) - Essential IP addresses (< 20 most-used IPs)
|
|
|
|
### Workflows & Operations
|
|
|
|
- [.claude/docs/COMMON-TASKS.md](.claude/docs/COMMON-TASKS.md) - SSH access, Caddy management, git workflow, script deployment
|
|
- [.claude/docs/HOME-ASSISTANT.md](.claude/docs/HOME-ASSISTANT.md) - HA config management, sync workflows, integrations
|
|
- [.claude/docs/CERTIFICATES.md](.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:**
|
|
```bash
|
|
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:
|
|
```bash
|
|
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:**
|
|
```bash
|
|
# 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
|