From f67af5f55d7f8b72e4db7f5f85099de57c792978 Mon Sep 17 00:00:00 2001
From: Ryan Malloy <ryan@supported.systems>
Date: Mon, 16 Feb 2026 07:50:00 -0700
Subject: [PATCH] Document production deployment process in CLAUDE.md

---
 CLAUDE.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 46 insertions(+), 6 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 313004c..dfb64c8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -192,16 +192,56 @@ Key files: `sgp4.cpp`, `sdp4.cpp`, `deep.cpp`, `common.cpp`, `basics.cpp`, `nora
 
 ## Documentation Site
 
-Starlight docs at `docs/` — 34 MDX pages covering all domains:
+**Live:** https://pg-orbit.warehack.ing
 
-```bash
-cd docs && npm run dev      # Dev server on :3000
-cd docs && npm run build    # Static build to dist/
-docker build --target production -t pg-orbit-docs docs/  # Caddy image
-```
+Starlight docs at `docs/` — 35 MDX pages covering all domains.
 
 Sections: Getting Started, Guides (8 domain walkthroughs), Workflow Translation (Skyfield/Horizons/GMAT/Radio Jupiter Pro comparisons), Reference (all 57 functions), Architecture (Hamilton's principles, constant custody, observation pipeline), Performance (benchmarks).
 
+### Local Development
+```bash
+cd docs && npm run dev      # Dev server on :4321
+cd docs && npm run build    # Static build to dist/
+```
+
+### Production Deployment
+
+The docs site deploys to the `warehack.ing` VPS (`149.28.126.25`) which runs caddy-docker-proxy with wildcard DNS for `*.warehack.ing`.
+
+**Deploy (or redeploy after changes):**
+```bash
+ssh -A warehack-ing@pg-orbit.warehack.ing
+cd ~/pg_orbit
+git pull origin phase/solar-system-expansion   # or the current branch
+cd docs
+make prod                                       # builds image + starts container
+```
+
+**First-time setup on VPS:**
+```bash
+ssh -A warehack-ing@pg-orbit.warehack.ing
+git clone git@git.supported.systems:warehack.ing/pg_orbit.git
+cd pg_orbit && git checkout phase/solar-system-expansion
+cat > docs/.env << 'EOF'
+COMPOSE_PROJECT_NAME=pg-orbit-docs
+NODE_ENV=production
+VITE_HMR_HOST=pg-orbit.warehack.ing
+EOF
+cd docs && make prod
+```
+
+**Makefile targets:**
+- `make prod` — build + start production (Caddy serves static files)
+- `make dev` — build + start dev mode (hot-reload, volume mounts)
+- `make down` — stop containers
+- `make restart` — stop + start production
+- `make clean` — stop + remove volumes
+- `make logs` — tail container logs
+
+**Infrastructure:** Container `pg-orbit-docs` joins external `caddy` network. caddy-docker-proxy reads labels to auto-configure reverse proxy + TLS (Let's Encrypt via Vultr DNS challenge). TLS cert provisioning takes ~2 minutes on first deploy.
+
+**Do NOT run the docs container locally** if also deployed on the VPS — competing ACME DNS challenges will corrupt each other's TXT records.
+
 ## Coding Style
 - Standard PostgreSQL extension C style
 - `ereport(ERROR, ...)` for user-facing errors, never `elog(ERROR, ...)`