What programs mean (the languages, translators, Mojo checker and
interpreter, prover, fuzzer, machine model, catalog problems and the Mojo
corpus with godbolt's stored answers) was mixed into the site's tree, so a
change to the prover and a change to a button went through the same gate
and the same docs. This moves all of it under core/, laid out as its own
repository, ready to be extracted with its history and pinned here as a
git submodule.
- core/: src/{engines,services,sync,mojo,exercises,curriculum,common},
mojo/, syntax/mojo.xml, its tests (with Workspace and workForProblem in
place of the site's Session), scripts (corpus pipeline, play, the
exercise and probe starters, engines export/diff), and its docs
(engines, trust, mojo-corpus, exercises, coverage). Its own pixi.toml,
package.json, README, AGENTS.md and CI workflow.
- core/tests/boundary.test.mjs: library modules use no DOM, import no
page widget, and import nothing outside src/.
- core/scripts/cli.mjs: pixi run cli check|run|prove|fuzz|translate.
- core/scripts/dafny.py: Dafny 4.11.0 pinned by version and SHA-256 per
platform, fetched into .tools/ (pixi run dafny-fetch, pixi run dafny).
- The site imports core only as #core/<path>.js: an import map in
index.html, "imports" in package.json for node, core's declarations for
tsc. The site's TypeScript builds core first (npm run build).
- assemble.sh, the Quarto engine copy, the render cache key, check-pages,
quarto-export and quarto-css read core/dist and core/mojo; quarto-css
copies core's syntax/mojo.xml into the extension.
- Site tests that covered engines moved to core; the rest keep Session.
- README, AGENTS.md, docs/app.md, docs/deploy.md and the CI workflow
describe the split (checkout with submodules; core's tests and corpus
status run against the pinned commit).
Gate: site 110 pass; core 307 pass; corpus status --strict passes.
Manual check: the assembled site opens Bridge (count-base-proved),
Developer and Hardware (count-base) with the editor, the stepper and the
board, and no module errors.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FgvbRdoEheAHqsRmr2WuKZ
3.9 KiB
Deploying
The site builds against pplus-core, the git submodule core/, at the commit this repository pins. A checkout needs it (git clone --recurse-submodules, or git submodule update --init); npm run build builds core first. To take a newer core: git -C core pull (or check out a tag), pixi run test, and commit the new core pointer with what it changes on this side.
pixi run site tests the app and assembles site/; pixi run deploy [slug] [user@host] does that and publishes it. CI (.gitea/workflows/deploy.yml) does the same on every push to main.
The site is six things: index.html, styles.css, styles/ (the course's widget styles, which the Hardware area's machine views use), dist/, core/ (pplus-core's built core/dist/, which index.html's import map names as #core/), and the Quarto extension (quarto/_extensions/pplus, without an engine copy), which the With Quarto page loads (pplus.css, pplus.js) and links to file by file. scripts/assemble.sh copies them into site/ with a VERSION file holding the commit, and scripts/deploy.sh <slug> [user@host] publishes site/ to /srv/www/<slug> as an atomic release:
/srv/www/pplus -> symlink to the live release
/srv/www/pplus.releases/ one directory per deployed commit, the five newest kept
The swap is one rename, so nobody sees a half-copied site, and a rollback is ln -sfn /srv/www/pplus.releases/<sha> /srv/www/pplus. A pre-existing plain directory at /srv/www/<slug> is moved to <slug>.releases/before-releases on the first run.
Caddy: Caddyfile is the site block (root on the symlink, file_server, no-cache on the modules so a new deploy is picked up on the next load, 404s rewritten to the app, and frame-ancestors so course pages can embed views). The live shortcodes and live="click" put the app in an iframe, so a Quarto site on another origin needs that origin added to frame-ancestors; the rendered views need nothing from the host. Caddy issues the certificate itself; add the block to /etc/caddy/Caddyfile and systemctl reload caddy.
Gitea Actions without a container image (.gitea/workflows/deploy.yml): the act_runner on the droplet runs jobs on the host shell instead of in docker. Once, on the droplet:
# tools the job uses
apt install -y git rsync curl
curl -fsSL https://deb.nodesource.com/setup_22.x | bash - && apt install -y nodejs # or any node >= 20
# a user for the runner that owns the web root
useradd -m -s /bin/bash deploy
mkdir -p /srv/www && chown deploy:deploy /srv/www
# register the runner with a host-mode label (the :host suffix is the whole trick)
sudo -u deploy act_runner register --instance https://<your-gitea> --token <runner token> --labels "quarto-deploy:host" --no-interactive
# run it as a service (act_runner generate-config > config.yaml; systemd unit per the Gitea docs, User=deploy)
With that label, runs-on: quarto-deploy executes steps directly as deploy, with the host's node, git, and rsync; actions/checkout works because node is on the host, and no image is pulled. The job checks out the pinned core with the site (submodules: recursive; the runner's token must be able to read pplus-core), builds, runs the tests, checks that our Mojo programs pass (core's corpus.py status --strict, offline), assembles site/, and on main runs scripts/deploy.sh into /srv/www. SITE_SLUG (repository variable) names the directory and defaults to the repository name; set it to pplus. SITE_URL turns on a smoke test that fetches /VERSION from the live site and fails the job if it is not the deployed commit.
If the runner ever moves off the droplet, scripts/deploy.sh pplus deploy@droplet rsyncs over SSH instead; give that runner a key whose public half is in deploy's authorized_keys.
By hand, on the droplet: pixi run deploy pplus. From elsewhere: pixi run deploy pplus deploy@droplet.