Operations: installing, layout and jobs

Requirements

Install and update

server/install.sh              # copy server/ to dh, install site files and hooks
server/install.sh --publish    # ...and republish every repo
runner/install.sh              # CI runner on TrueNAS: copy it, make its ssh key, add the cron job
runner/install.sh --authorize  # ...and allow that key on DreamHost (runner-api only)
runner/install-laptop.sh       # the laptop as a polite second runner (launchd, Docker, its own venv)
vscode-web/install.sh          # VS Code in the browser at apps.fuzzyworld.net/vscode/

install.sh copies server/ from the working copy, not from a commit, so uncommitted changes there go live too.

npm run deploy (the usual way)

bin/deploy-tools [server|runner|laptop-runner|vscode|all] [--force] wraps the install scripts with a ledger kept on the server, ~/fw/state/deployed.json.

• Targets are declared in this repo's package.json: "fuzzyworld": {"deploy": {"<target>": {"paths": [folders it ships], "command": [script, args], "description": "...", "perMachine": true}}}.

• The ledger records, for each <repo>/<target>, the commit and a content hash of the folders that target ships. A target is redeployed only when that hash differs. So uncommitted edits count, unrelated commits (README, tests) do not, and committing the files you already deployed does not trigger a second deploy. Gitignored files in those folders are not hashed.
• Ledger keys used to be bare (server, laptop-runner@<hostname>). bin/deploy-tools renames such a key to <repo>/<target> in memory when it loads the ledger (an existing new key wins), and the next successful deploy saves the result. Times in the ledger are the laptop's local time.
• The ledger is written only after the script succeeds, and any laptop sees the same state. The exception is laptop-runner, which is installed per machine and so is recorded per hostname (key <repo>/laptop-runner@<hostname>).
• fw deploys and the admin panel read the same ledger.
• For flags deploy-tools does not pass (--authorize, --remove, --out) run the install script directly. To regenerate pages without installing, run bin/fw publish-all.

Layout on DreamHost

Sites and code

Tools and state (outside every web root)

Scheduled jobs

Jobs live in server/jobs/. install.sh writes server/jobs/crontab into the DreamHost crontab, between # fw:begin and # fw:end; it replaces only that block. Cron wakes each job hourly. DreamHost's clock is Pacific time, so each job checks its own UTC schedule, and daylight saving can't shift it.

Run one by hand: ssh dh '~/fw/tools/server/jobs/north-star-cleanup.sh --now --preview-only' (without --preview-only for the real thing).

Secrets are in ~/.config/<project>.env on DreamHost (mode 600, never in a repo or the web root). north-star.env holds FIREBASE_TOKEN.

Node on DreamHost

The system Node is 18. Jobs use Node 22 from ~/fw/node (the official linux-x64 build; checksum-verified), always with NODE_OPTIONS=--jitless: DreamHost's grsec kernel refuses executable memory, so V8's JIT crashes without it. npm installs use --ignore-scripts, because native addons can't be built there. jq 1.7.1 (the official static build) is in ~/bin.

VS Code in the browser

apps.fuzzyworld.net/vscode/?repo=<name> opens a public repo in VS Code. It is linked from each summary page.

What it is: the open-source VS Code web build (the vscode-web npm package, 1.91.1, MIT) plus vscode-web/fw-fs/, an extension that reads files.json and objects/<sha> from code.fuzzyworld.net. Everything is static files.

• Works: quick open (Ctrl/Cmd+P), and search across files (text files up to 256 KB).
• Read-only: nothing can be changed; clone to edit.
• Not yet: Markdown preview and other webviews (they need a separate domain per view), and project-wide TypeScript IntelliSense (turned off; syntax colors work).

The plain "Open in VS Code" link (vscode://vscode.git/clone?url=…) clones the repo into the visitor's own VS Code.