Repo build logic now runs as the unprivileged docsbuild user with a scrubbed environment; the Cloudron token lives only in a root-owned publish script that executes no repository code.
Publishing the documentation site
The Markdown in this repository is the single source of truth. This directory is the publishing layer that turns it into a member-readable static site and puts it on the co-op's docs Surfer app at https://docs.inference.coop/. Documents are never edited here — a change to a document is a normal commit or pull request against the Markdown at the repository root.
What is built
| File | Purpose |
|---|---|
../mkdocs.yml |
Site configuration (MkDocs + Material for MkDocs) |
brand.css |
Co-op palette + self-hosted Figtree webfont (SIL OFL 1.1) |
fonts/ |
Figtree woff2 files and the OFL licence text |
logo.svg |
Co-op logo (shared with the website repo) |
build.sh |
Stage the Markdown into .site-src/, render to .site-build/ |
hooks.py |
MkDocs hooks: directory-link rewriting + content-hashed stylesheet URLs |
deploy.sh |
Manual publish of the build into the Surfer app (needs a Cloudron token) |
poll-watcher.sh |
Legacy poller; no longer installed — superseded by the host-owned poller |
docs-deploy-poll.service |
systemd unit for the poller (runs the host-owned script) |
webhook-receiver.py |
Webhook receiver; not installed (see below) |
webhook-receiver.service |
systemd unit for the receiver; not installed |
requirements.txt |
Pinned Python build toolchain |
Nothing external is loaded by the site: no CDN, no third-party font service. Fonts are served from this repository's own output.
Cache-proof stylesheets
brand.css and typography.css are listed under extra_css, so at a fixed URL
they would be vulnerable to a stale browser cache after a deploy — a warm cache
keeps serving the old file because the URL never changes. hooks.py's
on_post_build fixes this at build time: it copies each stylesheet to
<name>.<sha256-8>.css in the output and rewrites the <link> in every built
page to the hashed name. A change to a stylesheet's content therefore always
produces a new URL. The authored sources keep their names and locations; the
hashed copies exist only in the build output. The hashed copy sits in the same
directory as the original, so the @font-face url("fonts/…") references keep
resolving. The deploy is unchanged.
Build
publishing/build.sh # creates .venv-docs on first run
Output lands in .site-build/ (gitignored). mkdocs build --strict is what
CI-style runs should use, so broken links fail the build.
Deploy
CLOUDRON_TOKEN=... publishing/deploy.sh
Writes the build into the docs Surfer app (Cloudron app docs.inference.coop,
io.cloudron.surfer) at:
/app/data/public/— served at https://docs.inference.coop/
That is now the one canonical location. The docs used to be a pair of
directories inside the marketing Surfer app (inference.coop) as well, at
/app/data/public-docs/ and /app/data/public/docs/; both were deleted when
this app took over, so https://inference.coop/docs/ no longer serves the docs
(nothing on the marketing site linked to it).
Override the destination with SURFER_APP (the app's Cloudron location) and
DOCS_DEST (path inside the container) if you ever need to.
Automatic rebuilds (push to main)
docs-deploy-poll.service polls Gitea every 60 seconds and deploys whenever
main moves, so a push appears on the site within about a minute with no human
action. Edit, commit, push — that is the whole deployment story.
The credential-bearing steps are host-owned, not repository code. The
poller runs a root-owned script (/usr/local/sbin/docs-poll) that does two
separate jobs:
- Build as
docsbuild. The repository's build logic (build.sh→ MkDocs →hooks.py) runs as an unprivileged system user with a scrubbed environment, from its own clean clone at/var/lib/docs-publisher/repowith its own venv. That user cannot read/home/ubuntu(mode 750), so repo code cannot see any co-op credential — the Cloudron token, the gateway master key, the agent's env file. - Publish with a root-owned script.
/usr/local/sbin/docs-publishruns no repository code. It takes only the built directory, writesmeta.json, and pushes it into the Surfer app usingCLOUDRON_TOKENfrom/etc/docs-deploy.env(root-only, mode 0600).
A commit that lands on main therefore cannot execute anything with the
Cloudron token. It can only influence the bytes of the site.
The webhook receiver is installed but not running. docs-deploy-webhook
is inactive and nothing listens on 8787. It predates this split, loads the
agent's env file, and runs repo scripts with the Cloudron token; do not enable
it without porting it to the same host-owned build/publish split. The Gitea
webhook registration is harmless while the receiver is down.
Each deploy writes meta.json into the site with the commit it was built
from, so a deploy can be verified from the served site itself:
https://docs.inference.coop/meta.json
If a deploy breaks, roll back with the saved unit
(/root/docs-deploy-poll.service.before-split) and the previous build in
/var/lib/docs-publisher/repo/.site-build; the poller retries every 60 seconds
and sends one Matrix alert after 3 consecutive failures.
Build environment
publishing/requirements.txt pins every package the build needs (mkdocs,
mkdocs-material, mkdocs-redirects). build.sh verifies the build venv
against it before every build and installs anything missing or off-version
(fast local no-op when current); it also fails loudly if mkdocs.yml
configures a plugin that requirements.txt does not pin.
The deployed poller keeps one build venv at
/var/lib/docs-publisher/repo/.venv-docs, owned by docsbuild. A manual
publishing/build.sh uses .venv-docs in whatever checkout you run it from;
that is fine for local previews and does not affect deploys.