How do I serve the site locally?

How do I preview the ORE Studio documentation site on my local machine?

Build, then start a systemd-managed background server (most common):

./compass.sh build --direct site
./compass.sh site start

Then open http://localhost:<ORES_SITE_PORT>/OreStudio/ in a browser (ORES_SITE_PORT comes from .env; fallback default is 51004 when ORES_SITE_PORT is not set). site start also prints the LAN URL, for checking the preview from another device.

Check whether it's running, and stop it:

./compass.sh site status
./compass.sh site stop

Foreground, interactive use instead (Ctrl-C to stop):

./compass.sh site serve --compile

--compile rebuilds first; omit it to serve an already-built build/output/site/. --port <N> overrides the resolved port, same precedence as below.

compass build --direct site (equivalently, compass site serve --compile) runs emacs -Q --script projects/ores.lisp/src/ores-build-site.el from the repo root, which publishes every .org file to HTML under build/output/site/.

compass site start renders and deploys a concrete (not templated) systemd --user unit – site-<env>.service, built directly from ORES_ENV_NAME in this checkout's own .env – and starts it via systemctl --user. The unit's ExecStart runs python3 -m http.server directly against build/output/site/, no wrapper script or PID-file bookkeeping: systemd itself owns the process via its cgroup, the same way every other ORE Studio service does (see How do I start the ORE Studio services?). Unlike the main fleet, this unit is standalone – not PartOf=/=Wants-linked to ores-<env>.target – since previewing the site is an occasional dev convenience, not something every fleet start/stop should cascade to. It does not rebuild the site itself: run compass build --direct site first whenever the content changes, then site start (or just leave it running and rebuild again – the already-running server picks up the new files immediately, since it serves the directory live).

compass site serve (no start=/=stop=/=status) is the older, simpler foreground path: still useful for a quick interactive check without touching systemd at all, and the only form that supports --compile directly.

Pages are served directly under /OreStudio/ to match the GitHub Pages URL structure (orestudio.github.io/OreStudio/).

The port is resolved in this order: --port flag (serve only) → ORES_SITE_PORT from .env → 51004 (last-resort default when ORES_SITE_PORT is not set).

Emacs must be on PATH (for building). systemctl --user must be available (for start=/=stop=/=status – true on any host already running the rest of the ORE Studio fleet via systemd). No CMake configure step required — compass runs independently of the build system.

Manual preview before pushing documentation changes. The build-site.yml GitHub Action publishes the site on every push to main and is the integration test for the full pipeline.

• How do I deploy the site? — compass build --direct site (same Emacs step, no HTTP server).
• How do I start the ORE Studio services? — the same systemd --user pattern, for the full service fleet.
• How do I deploy the skills? — publish Claude Code skills alongside the site.
• How do I create a new doc? — add org files that will appear in the compiled site.