Document catalog host moves and add per-module host-deps installer.
Some checks are pending
offline / test (push) Waiting to run

zapier-docs-master now has CATALOG-HOST.md (relative PDFs / rewrite-docs-host.py)
and HOST-DEPS.md. verae-bootstrap/scripts/host-deps.sh checks and installs
git, Node, native build tools, and nats-server on Debian or Alpine from
host-deps.tsv (every Forgejo module). fetch.sh runs it before clone/npm.
This commit is contained in:
George Lambert 2026-09-11 23:12:25 -04:00
parent 20155de96b
commit 2d51d7a0dd
17 changed files with 629 additions and 9 deletions

View file

@ -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 PDFs 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
```

View file

@ -0,0 +1,22 @@
# Host dependencies for every Forgejo module
The installer lives in **verae-bootstrap** (not this summaries repo):
- Script: `scripts/host-deps.sh`
- Manifest: `host-deps.tsv` (one row per Forgejo repo)
- Narrative: [HOST-DEPS.md](https://git.georgelambert.org/marchon/verae-bootstrap/src/branch/main/HOST-DEPS.md)
It detects Debian/Ubuntu vs Alpine (and best-effort macOS), checks that git, curl, Node, native build tools, and `nats-server` are present, and **downloads/installs** whatever is missing on **this** machine.
```bash
git clone ssh://git@git.georgelambert.org:2223/marchon/verae-bootstrap.git
cd verae-bootstrap
bash scripts/host-deps.sh --check --type ns1-all-in-one
bash scripts/host-deps.sh --type ns1-all-in-one
export VERAE_SRC=$HOME/verae-src
bash scripts/fetch.sh ns1-all-in-one
```
Alpine if `bash` is not installed yet: `apk add --no-cache bash git curl`.
Catalog hostname move (relative PDFs): [CATALOG-HOST.md](CATALOG-HOST.md).

View file

@ -3,6 +3,8 @@
Summaries, NATS contracts, and message flows for every Verae Time × Zapier module.
**Live catalog:** https://zapier.georgelambert.org/
**Move the catalog to another host:** [CATALOG-HOST.md](CATALOG-HOST.md) (relative PDF links; `scripts/rewrite-docs-host.py`)
**Host OS / Node / NATS install:** [verae-bootstrap HOST-DEPS](https://git.georgelambert.org/marchon/verae-bootstrap)
**Overview (start here):** https://git.georgelambert.org/marchon/overview
**Operator console:** http://127.0.0.1:3850/ (Fleet · Trace · Docs)
**Monorepo:** https://git.georgelambert.org/marchon/master-zapier-plan-draft (`main` and `master`)

View file

@ -1,3 +1,5 @@
# verae-bootstrap
Clone Forgejo modules and install npm deps. Server types under `types/`.
`scripts/host-deps.sh` checks this machine (Debian/Ubuntu or Alpine) and installs git, curl, Node, build tools for `better-sqlite3`, and `nats-server` when the server type runs JetStream locally. Manifest: `host-deps.tsv`. See `HOST-DEPS.md`.