Files
docs/publishing/README.md
T

132 lines
6.1 KiB
Markdown

# 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.in` | Human-edited pins for the build toolchain |
| `requirements.txt` | Hash-locked toolchain generated from `requirements.in` |
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
```sh
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
```sh
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:
1. **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/repo`
with 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.
2. **Publish with a root-owned script.** `/usr/local/sbin/docs-publish` runs
no repository code. It takes only the built directory, writes `meta.json`,
and pushes it into the Surfer app using `CLOUDRON_TOKEN` from
`/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.in` pins every package the build needs (`mkdocs`,
`mkdocs-material`, `mkdocs-redirects`); `publishing/requirements.txt` is the
generated hash-locked lockfile. `build.sh` verifies the build venv against
`requirements.in` before every build, installs from the lockfile with
`--require-hashes`, and fails loudly if `mkdocs.yml` configures a plugin that
`requirements.in` does not pin.
Regenerate the lockfile after editing pins:
```
pip-compile --generate-hashes --strip-extras \
--output-file publishing/requirements.txt publishing/requirements.in
```
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.