f3017b9ab5
Track all active Proxmox swarm stack YMLs, NATS config, Postgres init SQL, and env generation script. Update .gitignore for homelab project. Add CLAUDE.md for project context. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
57 lines
2.6 KiB
Markdown
57 lines
2.6 KiB
Markdown
# 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
|