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
37 lines
3.9 KiB
Markdown
37 lines
3.9 KiB
Markdown
# 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`](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:
|
|
|
|
```bash
|
|
# 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`.
|