ZDDC/bootstrap/README.md

Deployment bootstrap

ZDDC tools (archive, transmittal, classifier, mdedit, landing) are single-file HTML bundles. The bootstrap pattern lets you install once on a deployment and update by editing a few lines, without re-uploading multi-megabyte HTML files.

End users install via the unified install.sh script, served at https://zddc.varasys.io/install.sh. The script handles all three deployment patterns (self-contained / channel-tracking / pin-to-version) plus both target shapes (deployment root or project subdirectory) via a single command:

sh -c "$(curl -fsSL https://zddc.varasys.io/install.sh)" -- [options]

The published stubs live under https://zddc.varasys.io/bootstrap/:

• bootstrap/level1/<tool>.html — same-origin level-1 stubs (4 tools, no landing — landing only lives at deployment root).
• bootstrap/track-{stable,beta,alpha}/<tool>.html — per-channel level-2 stubs (5 tools each).

Both directories are produced by the project's top-level build.sh from bootstrap/level{1,2}.html.tmpl. install.sh orchestrates which stubs to fetch and where to put them based on --mode / --target / --channel.

The two-level model

A typical zddc-server deployment looks like this:

<ZDDC_ROOT>/
  index.html                # landing tool (or bootstrap)
  archive.html              # archive tool (or bootstrap; site-wide channel switch lives here)
  transmittal.html
  classifier.html
  mdedit.html
  <project-A>/
    archive.html            # level-1 bootstrap → fetches ../archive.html
    transmittal.html
    classifier.html
    mdedit.html
    <project files…>
  <project-B>/
    archive.html            # level-1 bootstrap (or pinned to a specific version)
    …

• Level-1 stubs at <project>/<tool>.html always fetch the same-origin ../<tool>.html. They never touch zddc.varasys.io. Install them once; they don't need to change.
• At deployment root (<ZDDC_ROOT>/<tool>.html), put either:
  • the actual built tool HTML — fully self-contained install, no external dependencies; or
  • a level-2 bootstrap — fetches <source>/releases/<tool>_<channel>.html directly (that path is a checked-in symlink on the upstream that resolves to the current channel mirror). No manifest lookup, no version arithmetic, no Codeberg proxy magic — every URL is a real static file or a static symlink chain.

The site administrator switches the whole site to a channel by re-running install.sh --mode track --channel <name> — that overwrites the root <tool>.html files with the matching level-2 stubs. A single project can override one tool by editing just <project-X>/<tool>.html (replace the relative upstream URL with an absolute zddc.varasys.io URL pointing at the desired version, channel mirror, or partial-version pin).

Why two levels

The level-1 stubs let projects share a single source of truth for "which build of the archive tool runs here." Switching channels is one file change at the root; pinning a single project is one file change in that directory.

document.write() chains across both levels: level-1 fetches and writes, the new document's level-2 script runs and writes again, the third write is the actual tool. Origin stays at the deployment domain throughout, so File System Access API, crypto.subtle, and localStorage all work and preferences stay scoped to the deployment.

Pinning options

There are two ways to choose a version: edit the stub for a permanent pin, or pass a ?v= URL parameter for a per-request override.

1. Permanent pin (point the stub at a fixed URL)

The default level-2 stub fetches <source>/releases/<tool>_<channel>.html — which is itself a symlink on the upstream that resolves to the current channel mirror. To pin permanently, change the URL inside the stub:

Target stability	URL the stub should fetch
Exact stable version	https://zddc.varasys.io/releases/<tool>_vX.Y.Z.html
Latest patch within <X.Y>.*	https://zddc.varasys.io/releases/<tool>_v<X.Y>.html (symlink)
Latest within <X>.*.*	https://zddc.varasys.io/releases/<tool>_v<X>.html (symlink)
Track stable channel (default)	https://zddc.varasys.io/releases/<tool>_stable.html (symlink)
Track beta / alpha channel	https://zddc.varasys.io/releases/<tool>_<channel>.html

2. Per-request ?v= parameter

Both stub levels honor a ?v= URL parameter. The parameter survives the document.write() chain, so it flows through level-1 → level-2 → upstream automatically.

URL parameter	Resolves to
?v=0.0.4 (or ?v=v0.0.4)	<tool>_v0.0.4.html (exact)
?v=0.0 (or ?v=v0.0)	<tool>_v0.0.html (latest 0.0.x patch — symlink)
?v=0 (or ?v=v0)	<tool>_v0.html (latest 0.x — symlink)
?v=stable	<tool>_stable.html
?v=beta	<tool>_beta.html
?v=alpha	<tool>_alpha.html
(omitted)	the default channel baked into the stub at install time

When level-1 has ?v=…, it tries ../<tool>_<suffix>.html first (useful when the admin has staged specific versions locally — the upstream's symlink layout works the same locally) and falls back to ../<tool>.html if 404 — which then forwards the parameter via level-2 if one is installed.

Stable per-version files are immutable. The <tool>_stable.html, <tool>_beta.html, and <tool>_alpha.html symlinks (or real bytes when a channel has active dev) get updated whenever the relevant channel advances upstream — expect them to change. The build label rendered on the tool page tells you exactly which build you're seeing (v<next-stable>-{alpha,beta} · <date> · <sha> for channel mirrors, v<X.Y.Z> for pinned stables).

Auditing what's installed

Every stub contains a fallback (level-1) or upstream (level-2) constant. To see what each tool / project on the deployment points at:

grep -rn "fallback\|upstream" <ZDDC_ROOT>

CORS prerequisite (level-2 only)

A level-2 fetch is cross-origin (deployment → zddc.varasys.io). The upstream must serve Access-Control-Allow-Origin: * (or a list including your deployment origin) on each released asset. Verify with:

curl -I https://zddc.varasys.io/releases/archive_stable.html | grep -i access-control
curl -I https://zddc.varasys.io/releases/archive_v0.0.2.html | grep -i access-control

Level-1 fetches are same-origin so no CORS is involved.

Templates

level1.html.tmpl and level2.html.tmpl are the source of truth. The project's top-level build.sh substitutes {{TOOL}}, {{TOOL_TITLE}}, {{CHANNEL}}, and {{FAVICON}} to produce the per-tool stubs published under website/bootstrap/level1/ and website/bootstrap/track-<channel>/, which the install snippets curl from https://zddc.varasys.io/bootstrap/.