Three-node NATS JetStream cluster on Proxmox LXC

2026-09-11 23:48:02 -04:00 · 2026-09-11 23:48:02 -04:00 · f8396325e4
commit f8396325e4
79 changed files with 801 additions and 0 deletions
--- a/CATALOG-HOST.md
+++ b/CATALOG-HOST.md
@ -0,0 +1,81 @@
+# Move the documentation catalog to another hostname
+
+The catalog is a **static tree** (`site/` in the monorepo). HTML cards and PDF clicks are **path-relative**, so the same files can be served from `https://zapier.georgelambert.org/` today and `https://docs.verae-time.net/` later without rewriting links.
+
+Live service doors (portal, IAM, fleet, …) stay on their own hostnames. Forgejo stays on `git.georgelambert.org`.
+
+**Script:** `scripts/rewrite-docs-host.py` in [master-zapier-plan-draft](https://git.georgelambert.org/marchon/master-zapier-plan-draft)  
+**Build:** `scripts/build-docs-site.py` · **Deploy:** `scripts/deploy-docs-site.sh`
+
+## Default (relative) — no hostname pass
+
+1. Build: `python3 scripts/build-docs-site.py`
+2. Rsync the `site/` directory to the new host document root (must be the site root, `/`).
+3. Point DNS + TLS (Caddy `file_server` with `index index.html index.pdf README.html README.pdf`) at that tree.
+
+PDF annotations look like `README.pdf` and `../../index.html` (relative to the PDF). Browsers resolve them against the PDF’s own URL, so they follow the new host.
+
+Optional label in the HTML banner (not a link target):
+
+```bash
+DOCS_PUBLIC_HOST=docs.verae-time.net python3 scripts/build-docs-site.py
+```
+
+## Absolute URLs (only if a viewer needs them)
+
+Bake a public origin at build time:
+
+```bash
+DOCS_PUBLIC_URL=https://docs.verae-time.net \
+DOCS_PUBLIC_HOST=docs.verae-time.net \
+  python3 scripts/build-docs-site.py
+```
+
+Or retarget an **already built** `site/` without rebuilding PDFs from markdown:
+
+```bash
+# Lab origin → future docs host
+python3 scripts/rewrite-docs-host.py \
+  --site ./site \
+  --from https://zapier.georgelambert.org \
+  --to https://docs.verae-time.net
+
+# Strip the origin (same as the default build)
+python3 scripts/rewrite-docs-host.py --site ./site --relative
+
+python3 scripts/rewrite-docs-host.py --site ./site --from … --to … --dry-run
+```
+
+The rewrite walks HTML/SVG/CSS/JS/MD text and PDF `/URI` annotations. It does **not** change `portal.zapier.georgelambert.org`, `iam.…`, or `git.georgelambert.org`.
+
+## Caddy (any host)
+
+```caddy
+docs.verae-time.net {
+	root * /SSD2/sites/docs.verae-time.net
+	encode gzip zstd
+	file_server {
+		index index.html index.pdf README.html README.pdf
+	}
+	try_files {path} {path}/index.html {path}/index.pdf {path}/README.html {path}/README.pdf
+}
+```
+
+Lab copy: `packages/verae-ops/caddy/zapier.georgelambert.org.caddy`.
+
+## Check
+
+```bash
+python3 scripts/check-doc-links.py
+```
+
+Local files must exist for homepage hrefs and PDF URI targets. Off-site HTTPS (Forgejo, live doors) is left alone.
+
+## Publish lab catalog (today)
+
+```bash
+git -C /Users/marchon/apps/zapier push ns1 main
+git -C /Users/marchon/apps/zapier push ns1 main:master
+bash scripts/deploy-docs-site.sh
+# → marchon@70.88.205.138:/SSD2/sites/zapier.georgelambert.org
+```