# 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