# CLAUDE.md

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

## Overview

Proxmox VE homelab cluster running Docker Swarm services. Three Proxmox hosts (pve, adder, game) connected via VXLAN overlay on vmbr1 (10.10.10.0/24). VMs run Docker CE and form a swarm with pve-postgres as manager.

## Deployment

All services deploy as Docker Swarm stacks from the manager node (pve-postgres). The active service definitions are in `proxmox/services/`. The `services/` directory contains older pre-migration copies.

```bash
# Generate env var prefix from pass (run locally)
./proxmox/services/gen-env.sh <service.yml>

# Copy yml to manager and deploy
scp proxmox/services/<service>.yml pve-postgres:~/
ssh pve-postgres "<ENV_VARS> docker stack deploy -c <service>.yml <stack_name>"

# Remove a stack
ssh pve-postgres "docker stack rm <stack_name>"
```

Secrets come from `pass` under the `homelab/` prefix. Use `gen-env.sh` to extract required `${VAR}` references from a yml and resolve them. Never hardcode secrets in files.

## Service YML Conventions

- All use `version: '3.8'` and Docker Swarm deploy mode
- Each service is pinned to a specific node via `node.hostname` constraint
- All connect to the external overlay network `homelab-net` via `${OVERLAY_NETWORK:-homelab-net}`
- Named volumes for persistence, `on-failure` restart policy with 3 max attempts
- Every service that has a web UI or accepts external connections must publish its ports
- Only include environment variables required to start the service — no optional/nice-to-have vars

## Cluster Topology

| Node | Host IP | Swarm IP | Role |
|------|---------|----------|------|
| pve | 192.168.40.198 | 10.10.10.1 | Proxmox host |
| adder | 192.168.40.150 | 10.10.10.86 | Proxmox host |
| game | 192.168.40.109 | 10.10.10.172 | Proxmox host |
| pve-postgres | — | 10.10.10.2 | VM on pve, swarm manager |
| pve-tools | — | 10.10.10.3 | VM on pve, swarm worker |
| adder-ghost | — | 10.10.10.20 | VM on adder, swarm worker |

## SSH Access

Use SSH config aliases (`pve-postgres`, `pve-tools`, `adder-ghost`, `pve`, `adder`, `game`). ProxyJump is configured in `~/.ssh/config`. Never manually hop through intermediate nodes.

## Key Files

- `proxmox/services/*.yml` — Active swarm stack definitions
- `proxmox/services/gen-env.sh` — Extracts env vars from yml, resolves from `pass homelab/`
- `proxmox/services/nats.conf` — NATS server config (JetStream, websocket, monitoring)
- `proxmox/services/01-init.sql` — Postgres init script (creates users/databases)
- `proxmox/post_init_node.org` — Fresh Proxmox node setup steps