Mikkel Georgsen
1b57dab4da
- Created TODO.md with pending task to fix ping on all containers - Added setcap command to standard container setup in documentation - Added detailed explanation in CLAUDE.md for future reference - Unprivileged containers need cap_net_raw on /bin/ping Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
134 lines
4.7 KiB
Markdown
134 lines
4.7 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Purpose
|
|
|
|
This is the management container (VMID 102) for Mikkel's homelab infrastructure. Claude Code operates here to assist with homelab management, automation, and maintenance tasks.
|
|
|
|
## Environment
|
|
|
|
- **Container:** LXC on Proxmox VE (core.georgsen.dk)
|
|
- **Network Access:** vmbr1 (10.5.0.0/24 internal), Tailscale
|
|
- **SSH Keys:** Pre-installed for accessing other containers/VMs
|
|
- **User:** mikkel (UID 1000, group georgsen GID 1000)
|
|
- **Python venv:** ~/venv (activate with `source ~/venv/bin/activate`)
|
|
- **Helper scripts:** ~/bin (pve, npm-api, dns)
|
|
- **Git repos:** ~/repos
|
|
|
|
## Living Documentation
|
|
|
|
**`homelab-documentation.md`** is the authoritative reference for all infrastructure details. This file must be kept current:
|
|
- Update when infrastructure changes are made
|
|
- Update when new services/containers are added
|
|
- Update when configurations change
|
|
- Update IP addresses, ports, and service mappings as they evolve
|
|
|
|
## Network Topology
|
|
|
|
```
|
|
Internet ─► vmbr0 (65.108.14.165) ─► NPM (10.5.0.1) ─► Internal services
|
|
├─ vmbr1: 10.5.0.0/24
|
|
└─ vmbr2: 10.9.1.0/24 (Hetzner vSwitch)
|
|
Tailscale mesh connects: PBS, Synology NAS, pve01, pve02, dev containers
|
|
```
|
|
|
|
## Key Infrastructure
|
|
|
|
| Service | IP | Access |
|
|
|---------|-----|--------|
|
|
| NPM (reverse proxy) | 10.5.0.1 | Admin :81 |
|
|
| DNS (Technitium) | 10.5.0.2 | :5380 or dns.georgsen.dk |
|
|
| PBS (backups) | 10.5.0.6 | :8007 or pbs.georgsen.dk |
|
|
| Dockge (docker mgmt) | 10.5.0.10 | :5001 |
|
|
| Forgejo (git) | 10.5.0.14 | :3000 or git.georgsen.dk |
|
|
| Tailscale relay | 10.5.0.x | Routes to 10.9.0.0/16 |
|
|
|
|
## PVE API Access
|
|
|
|
The `~/bin/pve` helper script provides API access to Proxmox:
|
|
```bash
|
|
~/bin/pve list # List all VMs/containers
|
|
~/bin/pve status <vmid> # Show status
|
|
~/bin/pve start <vmid> # Start VM/container
|
|
~/bin/pve stop <vmid> # Stop VM/container
|
|
~/bin/pve create-ct <vmid> <hostname> <ip> <disk_gb> # Create container
|
|
```
|
|
|
|
## NPM API Access
|
|
|
|
The `~/bin/npm-api` script manages Nginx Proxy Manager:
|
|
```bash
|
|
~/bin/npm-api --host-list # List proxy hosts
|
|
~/bin/npm-api --host-search <domain> # Search by domain
|
|
~/bin/npm-api --host-create <domain> -i <ip> -p <port> # Create proxy host
|
|
~/bin/npm-api --host-delete <id> # Delete proxy host
|
|
~/bin/npm-api --cert-list # List SSL certs
|
|
```
|
|
Note: SSL cert generation requires manual setup via web UI (http://10.5.0.1:81)
|
|
|
|
## DNS API Access
|
|
|
|
The `~/bin/dns` script manages Technitium DNS (internal zone: lab.georgsen.dk):
|
|
```bash
|
|
~/bin/dns list # List all zones
|
|
~/bin/dns records [zone] # List records in zone
|
|
~/bin/dns add <name> <ip> [zone] # Add A record (e.g., dns add myhost 10.5.0.50)
|
|
~/bin/dns delete <name> [zone] # Delete A record
|
|
~/bin/dns lookup <name> # Query DNS
|
|
```
|
|
|
|
## Common SSH Targets
|
|
|
|
```bash
|
|
ssh root@10.5.0.1 # NPM
|
|
ssh root@10.5.0.2 # DNS
|
|
ssh root@10.5.0.6 # PBS
|
|
ssh root@10.5.0.10 # Dockge
|
|
ssh root@10.5.0.14 # Forgejo
|
|
ssh mikkel@10.5.0.111 # dev container
|
|
```
|
|
|
|
## Important IPs
|
|
|
|
- **Home IP:** 83.89.248.247 (static, used for NPM access lists)
|
|
- **Public IP:** 65.108.14.165 (core.georgsen.dk)
|
|
|
|
## Security
|
|
|
|
- **Home IP:** 83.89.248.247 (whitelisted everywhere)
|
|
- **NPM Access List "home_only" (ID 1):** Restricts access to home IP only
|
|
- Applied to: dns.georgsen.dk, dockge.georgsen.dk, pbs.georgsen.dk
|
|
- **Fail2ban:** Running on PVE host (core) and Forgejo
|
|
- SSH jail on core, forgejo jail on Forgejo
|
|
- Bans after 5 failed attempts for 24 hours
|
|
- Whitelisted: 127.0.0.1, 10.5.0.0/24, 83.89.248.247
|
|
- **Firewall (core vmbr0):** Blocked ports: 53, 111, 3128, 8006, 8008 (home IP allowed)
|
|
|
|
## Container Management
|
|
|
|
**Update NPM:**
|
|
```bash
|
|
ssh root@10.5.0.1 'cd /opt/npm && docker compose pull && docker compose up -d'
|
|
```
|
|
|
|
**Enable ping in unprivileged containers:**
|
|
|
|
Unprivileged LXC containers drop `cap_net_raw` capability, causing ping to fail with "Operation not permitted". Fix by granting the capability to the ping binary:
|
|
|
|
```bash
|
|
# Run inside the container as root
|
|
setcap cap_net_raw+ep /bin/ping
|
|
|
|
# Or from PVE host
|
|
ssh root@10.5.0.254 'pct exec <vmid> -- setcap cap_net_raw+ep /bin/ping'
|
|
```
|
|
|
|
Note: Must be re-applied after `iputils-ping` package upgrades.
|
|
|
|
## User Preferences
|
|
|
|
- Python and Batch for scripting
|
|
- 256-color terminal retro aesthetic for UIs
|
|
- Ask clarifying questions rather than making assumptions
|
|
- Prefer understanding root causes over workarounds
|