Samantha Atkins f3017b9ab5 Add all swarm service definitions, CLAUDE.md, and gen-env.sh

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>

2026-03-29 03:51:11 -04:00

2.6 KiB

Raw Blame History

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.

# 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

2.6 KiB Raw Blame History