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 a short copy-paste shell snippet from the home page's "Install on your server" section. The snippet uses curl to fetch either the current stable HTMLs (self-contained) or tiny level-2 stubs (channel trackers) into the deployment directory. 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.

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 — resolves the desired channel against https://zddc.varasys.io/releases/manifest.json (or skips that step for an explicit ?v=X.Y.Z pin) and fetches the asset from https://zddc.varasys.io/releases/<tag>/<tool>_v<X.Y.Z>.html. Caddy at zddc.varasys.io reverse-proxies that to the corresponding Codeberg release-asset URL.

The site administrator switches the whole site to a channel by re-running the track-<channel> install snippet from the home page — 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).

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 (edit the stub)

The level-2 stub resolves channels via manifest.json at runtime, so a "pin to current stable" is the default — no editing required. To pin this single tool to a specific version permanently, replace the level-2 stub with one that bypasses the manifest:

To pin	Replace stub body with a fetch of
Exact stable version vX.Y.Z	https://zddc.varasys.io/releases/<tool>-vX.Y.Z/<tool>_vX.Y.Z.html
Specific alpha/beta build	https://zddc.varasys.io/releases/<tool>-vX.Y.Z-alpha.N/<tool>_vX.Y.Z-alpha.N.html
Channel default (current implementation)	Resolves <tool>-<channel> against releases/manifest.json at runtime

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	Behavior
?v=0.0.4 (or ?v=v0.0.4)	tries <tool>_v0.0.4.html locally, then upstream
?v=alpha	switches to alpha channel
?v=beta	switches to beta channel
?v=latest	latest stable
(omitted)	the default baked into the stub

When level-1 has ?v=…, it tries ../<tool>_<suffix>.html first (useful when the admin has staged specific versions locally) and falls back to ../<tool>.html if 404 — which then forwards the parameter via level-2 if one is installed. So the same URL works whether the version is staged locally, served by a level-2 stub, or both.

Stable releases are immutable. Alpha and beta channel files are overwritten in place each time their channel is rebuilt; expect them to change without notice. The build label rendered on the tool page tells you what you are running (date + commit SHA for alpha/beta, version number for stable).

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 manifest.json and on each released asset. Verify with:

curl -I https://zddc.varasys.io/releases/manifest.json    | grep -i access-control
curl -I https://zddc.varasys.io/releases/archive-v0.0.2/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/.