🚀 herald: deploy artifacts (prep — not applied) (opus)

serve.py binds loopback, so prod mirrors godstrument.pro: systemd runs serve.py,
nginx reverse-proxies the domain to 127.0.0.1:8147, certbot for TLS. Adds
deploy/{solargod.service, nginx-solargod.conf, deploy.sh, HERALD.md}. BLOCKED on
the user: domain/DNS + VPS access (Part ω.2). Nothing deployed — artifacts only.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

deploy/HERALD.md

@@ -0,0 +1,28 @@
+# HERALD — deploying SOLARGOD
+
+SOLARGOD is a static site + a stdlib `serve.py` that also proxies JPL
+(Horizons/SBDB/CAD) and disk-caches responses. `serve.py` binds **127.0.0.1 only**,
+so production is the same shape as godstrument.pro: **systemd runs serve.py on the
+loopback, nginx reverse-proxies the public domain to it, certbot adds TLS.**
+
+## What this directory gives you
+- `solargod.service` — systemd unit (`python3 serve.py 8147` in `/opt/solargod`).
+- `nginx-solargod.conf` — nginx server block → `127.0.0.1:8147` (replace `SOLARGOD_DOMAIN`).
+- `deploy.sh` — one-shot rsync + install + enable + reload (idempotent; re-run to update).
+
+## One-time
+```sh
+DOMAIN=orrery.example.com VPS=user@vps-host ./deploy/deploy.sh
+ssh $VPS 'sudo certbot --nginx -d orrery.example.com'
+```
+
+## ⚠ Blocked on you (cannot be done from the dev box)
+1. **Domain / DNS** — pick the hostname and point an A record at the VPS. (I don't
+   have your DNS or a chosen name — the whole lane waited on this per Part ω.2.)
+2. **VPS access** — the `VPS=user@host` with sudo, on the same box that serves
+   godstrument.pro (so the reverse-proxy pattern matches).
+3. Confirm Python 3 + nginx + certbot are present on the VPS (they are for godstrument).
+
+Give me the domain + VPS target and I'll run `deploy.sh` and verify the live site
+(orrery loads, planets move, `/verify.html` green, `/proxy/*` reaches JPL). Until
+then these artifacts are prepared but **not applied** — nothing has been deployed.

deploy/deploy.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# HERALD — deploy SOLARGOD to the VPS (rsync + systemd + nginx), mirroring the
+# godstrument.pro shape. Run from the repo root AFTER the DNS A record resolves.
+#   DOMAIN=orrery.example.com VPS=user@host ./deploy/deploy.sh
+# Idempotent: re-run to push updates (rsync --delete + service restart).
+set -euo pipefail
+: "${VPS:?set VPS=user@host}"
+: "${DOMAIN:?set DOMAIN=your.domain}"
+APP=/opt/solargod
+
+echo "→ syncing repo to $VPS:$APP"
+rsync -az --delete \
+  --exclude '.git' --exclude 'cache' --exclude 'assets/art/candidates' \
+  ./ "$VPS:$APP/"
+
+echo "→ installing service + nginx site on $VPS (domain: $DOMAIN)"
+ssh "$VPS" "bash -euo pipefail -s" <<EOF
+sudo install -m 644 $APP/deploy/solargod.service /etc/systemd/system/solargod.service
+sed 's/SOLARGOD_DOMAIN/$DOMAIN/g' $APP/deploy/nginx-solargod.conf \
+  | sudo tee /etc/nginx/sites-available/solargod >/dev/null
+sudo ln -sf /etc/nginx/sites-available/solargod /etc/nginx/sites-enabled/solargod
+sudo mkdir -p $APP/cache && sudo chown -R www-data:www-data $APP/cache
+sudo systemctl daemon-reload
+sudo systemctl enable --now solargod
+sudo systemctl restart solargod
+sudo nginx -t && sudo systemctl reload nginx
+EOF
+
+echo "✓ deployed. TLS:  ssh $VPS 'sudo certbot --nginx -d $DOMAIN'"

deploy/nginx-solargod.conf

@@ -0,0 +1,17 @@
+# HERALD — nginx reverse proxy for SOLARGOD. Replace SOLARGOD_DOMAIN, then run
+# certbot for TLS once the A record resolves. serve.py handles both static files
+# and the /proxy/* JPL endpoints (with its disk cache), so we proxy everything.
+server {
+    listen 80;
+    server_name SOLARGOD_DOMAIN;
+
+    # (optional perf) serve committed static assets straight from disk instead of
+    # through Python:  root /opt/solargod;  try_files $uri @app;  location @app { ... }
+    location / {
+        proxy_pass http://127.0.0.1:8147;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_read_timeout 90s;   # first cold Horizons spacecraft fetch can take 2–5 s
+    }
+}

deploy/solargod.service

@@ -0,0 +1,18 @@
+# HERALD — systemd unit for SOLARGOD. serve.py binds 127.0.0.1 only; nginx
+# reverse-proxies the public domain to it (mirror of the godstrument.pro shape).
+# Install: sudo cp deploy/solargod.service /etc/systemd/system/ && sudo systemctl enable --now solargod
+[Unit]
+Description=SOLARGOD orrery — serve.py (static + JPL Horizons/SBDB/CAD proxy + disk cache)
+After=network.target
+
+[Service]
+Type=simple
+User=www-data
+WorkingDirectory=/opt/solargod
+ExecStart=/usr/bin/python3 /opt/solargod/serve.py 8147
+Restart=on-failure
+RestartSec=3
+# serve.py writes its disk cache under WorkingDirectory/cache — keep it writable.
+
+[Install]
+WantedBy=multi-user.target