# ctrl/docs.sh

## Serving without the cluster or python

The docs are the instructions for building the cluster, so they must work before
anything else exists. That rules out serving them from the cluster, and it rules
out `python -m http.server` too — a minimal Debian has no python3. What it does
have, by definition, is Docker: the single prerequisite rig already demands. So a
throwaway nginx container serves a read-only bind mount.

nginx runs as the caller (`--user`), not as its own `nginx` user. A machine whose umask is
027 creates files readable by their owner and group only, and nginx's own user would get a
403 on every page. As the caller it reads whatever the caller can, so nobody has to chmod
their docs. Unprivileged, it listens on 8080 inside the container and keeps its pid and temp
files in /tmp.

It runs with a config of its own: one worker (nginx's `auto` starts one per core,
twelve on an ordinary laptop, for a handful of static pages), no access log and a
quiet entrypoint, so the terminal shows the URL and nothing else unless something
fails. The pages declare an empty icon, so the browser does not ask for a
`favicon.ico` that is not there.

## Committed SVGs

Rendered SVGs are committed alongside their `.dot` sources for the same reason:
the pages have to read on a machine with no Graphviz installed.

## Whose docs

`make docs` serves the docs of the folder it runs from. In rig that is rig's own `docs/`. A
project's launcher sets `DOCS_DIR` to its own `docs/` (an absolute path), so `make docs` there
serves the project's pages through this same script, on the same terms: an `index.html` at
the top, the environment's block for the port (`HTTP_PORT + 4`), a container named after the
environment. rig's own docs stay one `make -C <rig> docs` away. The project keeps no copy of
this script.