George Lambert
2d51d7a0dd
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.
81 lines
2.8 KiB
Markdown
81 lines
2.8 KiB
Markdown
# 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
|
||
```
|