# 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 [user@host]` publishes `site/` to `/srv/www/` 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/ /srv/www/pplus`. A pre-existing plain directory at `/srv/www/` is moved to `.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:// --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`.