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: build first, then site start. There is no need to stop the server to rebuild, since it serves the directory live and picks up new files immediately.

While editing documents, compass site page rebuilds the pages you have changed in about four seconds each, which is the loop to use when reviewing your own writing in the browser, and the check to run before committing. The full compass build --direct site is for the first build in a checkout. See How do I deploy the site? for which to use when.

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.