diff --git a/rig/.version b/rig/.version index 17e51c3..d917d3e 100644 --- a/rig/.version +++ b/rig/.version @@ -1 +1 @@ -0.1.1 +0.1.2 diff --git a/rig/ctrl/docs.sh b/rig/ctrl/docs.sh index a7e7010..584829d 100755 --- a/rig/ctrl/docs.sh +++ b/rig/ctrl/docs.sh @@ -1,6 +1,8 @@ #!/usr/bin/env bash # Documentation: render the diagrams, and serve the pages from a throwaway nginx container. # Usage: docs.sh serve | graphs +# Whose: DOCS_DIR, the docs/ of the folder `make docs` runs from (a project's launcher sets +# it); unset, rig's own. # Notes: docs/notes/docs.md set -euo pipefail cd "$(dirname "$0")" @@ -9,11 +11,13 @@ source ./lib/config.sh load_config REPO="$(cd .. && pwd)" +DOCS="${DOCS_DIR:-$REPO/docs}" +[ -d "$DOCS" ] && DOCS="$(cd "$DOCS" && pwd)" DOCS_PORT="${DOCS_PORT:-$((HTTP_PORT + 4))}" # +4 sits inside this env's block serve() { - if [ ! -f "$REPO/docs/index.html" ]; then - echo "no docs/index.html" >&2 + if [ ! -f "$DOCS/index.html" ]; then + echo "no index.html in $DOCS" >&2 exit 1 fi # One worker and no access log: a few static pages need no more, and the @@ -32,13 +36,14 @@ http { } NGINX chmod 644 "$DOCS_CONF" - echo "docs for '$CLUSTER' on http://localhost:${DOCS_PORT}" + echo "docs of $DOCS" + echo " for '$CLUSTER' on http://localhost:${DOCS_PORT}" echo " (ctrl-c to stop; nothing is installed and nothing persists)" docker run --rm \ --name "${CLUSTER}-docs" \ -e NGINX_ENTRYPOINT_QUIET_LOGS=1 \ -p "${DOCS_PORT}:80" \ - -v "$REPO/docs:/usr/share/nginx/html:ro" \ + -v "$DOCS:/usr/share/nginx/html:ro" \ -v "$DOCS_CONF:/etc/nginx/nginx.conf:ro" \ nginx:alpine } @@ -51,13 +56,13 @@ graphs() { fi shopt -s nullglob local found=0 f out - for f in "$REPO"/docs/graphs/*.dot; do + for f in "$DOCS"/graphs/*.dot; do out="${f%.dot}.svg" echo " graphviz $(basename "$f") → $(basename "$out")" dot -Tsvg "$f" -o "$out" found=1 done - [ "$found" -eq 1 ] || echo " no .dot files in docs/graphs/" + [ "$found" -eq 1 ] || echo " no .dot files in $DOCS/graphs/" } case "${1:-serve}" in diff --git a/rig/ctrl/selftest.sh b/rig/ctrl/selftest.sh index 0a501bd..f40ee43 100755 --- a/rig/ctrl/selftest.sh +++ b/rig/ctrl/selftest.sh @@ -193,6 +193,13 @@ check "the caller beats rig.env" "from-caller" \ # Identity follows the overlay's folder, so one rig serves several without collisions. check "identity follows the overlay's folder" "my-env kind-my-env" \ "$(in_ov env OVERLAY=local/My_Env bash ports.sh active | awk '{print $1, $2}')" +mkdir -p "$OVR/local/renamed"; printf 'CLUSTER=pinned\n' > "$OVR/local/renamed/rig.env" +check "rig.env's CLUSTER names it, whatever the folder" "pinned kind-pinned $(derive_port_base pinned)" \ + "$(in_ov env OVERLAY=local/renamed bash ports.sh active | awk '{print $1, $2, $3}')" +check "the caller's CLUSTER beats rig.env's" "second kind-second" \ + "$(in_ov env OVERLAY=local/renamed CLUSTER=second bash ports.sh active | awk '{print $1, $2}')" +check "make docs serves DOCS_DIR, the folder it runs from" "no index.html in $OVR/local/renamed" \ + "$(in_ov env DOCS_DIR="$OVR/local/renamed" bash docs.sh serve 2>&1 >/dev/null | head -1)" check "paths in rig.env are relative to the overlay" "$OVR/local/My_Env/k8s/prod" \ "$(in_ov env OVERLAY=local/My_Env bash ports.sh active | awk '{print $7}')" check "a named overlay that does not exist is an error" "yes" \ diff --git a/rig/docs/notes/docs.md b/rig/docs/notes/docs.md index 7348528..a39f11a 100644 --- a/rig/docs/notes/docs.md +++ b/rig/docs/notes/docs.md @@ -18,3 +18,12 @@ fails. The pages declare an empty icon, so the browser does not ask for a 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 docs` away. The project keeps no copy of +this script. diff --git a/rig/docs/notes/overlay.md b/rig/docs/notes/overlay.md index 6886340..0cc5940 100644 --- a/rig/docs/notes/overlay.md +++ b/rig/docs/notes/overlay.md @@ -74,6 +74,36 @@ follow the overlay folder's name, sanitised the same way a rig folder's name is. One rig can therefore serve several overlays, each in its own cluster, and a project that carries rig at `./rig` does not name every cluster `rig`. +That is the default. The convention is to pin the name in the overlay's `rig.env`: + +``` +CLUSTER= +``` + +The name only has to be unique on the machine: the port block derives from it, so two +overlays with the same name share one cluster and one set of ports. Pinned, it no longer +follows the folder, so moving or renaming folders changes nothing. A second copy of the +same project (another worktree, say) runs beside it by setting its own `CLUSTER=` in the +project's ignored `.env.local`: the caller beats `rig.env`. Ports the workload forwards +itself (a Tiltfile's `port_forwards`) are the overlay's, not the block's, and can still +collide. + +A repository that runs on rig keeps it in a `devenv/` folder, with rig as the project's +sibling: + +``` +devenv/ + rig/ rig + / the forwarder (RIG_DIR ?= $(HERE)/../rig), its knobs, its data + overlay/ what rig reads +``` + +The overlay folder is then called `overlay/` in every project, so its name says nothing +and `CLUSTER=` in its `rig.env` is required, not optional: left to the default, every such +project would be the cluster `overlay`, on the same ports. The project folder, the cluster +and the workload's namespace are three names: a folder may hold `_`, the other two are DNS +labels. + `ports.sh persist` refuses while an overlay is set: it writes to rig's `ctrl/.env`, and a pin there would follow every overlay. @@ -164,6 +194,9 @@ RIG_DIR ?= $(HERE)/rig override RIG_DIR := $(abspath $(patsubst ~/%,$(HOME)/%,$(RIG_DIR))) ``` +`make docs` should serve the project's pages, not rig's: the forwarder names them with +`DOCS_DIR := $(HERE)/docs` (see docs.md). rig's own stay `make -C docs`. + No search path: an unset `RIG_DIR` means `./rig`, and nothing else is tried. Moving rig changes nothing in the cluster's name, context or ports; moving or renaming the overlay folder does.