rig major updates

rig/BOOTSTRAP.md

@@ -1,18 +1,9 @@
-# From a machine with nothing on it to a project you can work in
+# From a machine with nothing on it to an environment you can work in
 
 The README says the prerequisite is Docker and nothing else. This is what that
-actually looks like end to end: a bare Linux box, and a new project running under
+actually looks like end to end: a bare Linux box, and an overlay running under
 Tilt at the end of it.
 
-A copy of this directory is a sibling of it, named after the environment it
-models (`acme-rig`). Paths below are relative to the parent checkout.
-
-It spans three repos because the work does. **rig** prepares the machine — the
-pinned toolchain, the cluster, the port arithmetic. **all** owns the shape a
-project takes, in `all/projects/templates/conventions.md` and the `broad`
-scaffold beside it. **ppl** owns everything after local, and is where this
-document stops.
-
 Read it once before running anything. Three of the steps below need root and one
 needs a logout, so knowing about them in advance is cheaper than meeting them
 halfway through.
@@ -108,7 +99,7 @@ docker run --rm \
 ```
 
 The image name follows the directory, like everything else here: in `rig`
-it is `rig-deps`, in a copy called `acme-rig` it is `acme-rig-deps`. The
+it is `rig-deps`, in a copy called `other-rig` it is `other-rig-deps`. The
 tag is `deps` (or `full`, below), not `latest`.
 
 None of the four arguments are guessable, so:
@@ -183,80 +174,30 @@ worth reading before rather than after. `make cluster free <names>` stops
 clusters without deleting them; `docker start` brings them back untouched.
 
 
-## Scaffold the project
+## Start an overlay
 
-The canonical layout is [`all/projects/templates/conventions.md`](../all/projects/templates/conventions.md).
-Read it — it is short, opinionated, and exists precisely so nobody
-reverse-engineers a layout from whichever repo they happened to open. What
-follows is only the mechanical part.
+What runs lives outside rig, in an overlay — see
+[`docs/notes/overlay.md`](docs/notes/overlay.md). Start from rig's own:
 
 ```bash
-SLUG=<slug>                                    # short, lowercase, no separators
-cp -r ~/wdir/semester/all/projects/templates/broad ~/wdir/semester/"$SLUG"
-cd ~/wdir/semester/"$SLUG"
-grep -rl '<slug>' ctrl | xargs sed -i "s/<slug>/$SLUG/g"
-cp ctrl/k8s/.env.example ctrl/k8s/.env
-git init && git add -A && git commit -m "scaffold $SLUG from broad"
+cp -r examples/starter local/myenv       # local/ is gitignored by rig
+echo 'OVERLAY=local/myenv' >> ctrl/.env
+make check                               # shows the overlay, its cluster and ports
 ```
 
-`<slug>` is the only placeholder and it lives only under `ctrl/` — cluster name,
-namespace, ConfigMap name, and the `NAME=` in `kind-up.sh` / `kind-down.sh`. One
-sed does all of it.
-
-The slug is the folder name, lowercase and short — `mpr`, `unt`, `nvi`. The
-cluster takes that name and the context becomes `kind-<slug>`, derived by the
-scaffold's Makefile from the directory, so there is nothing to edit for either.
-
-**Pick the Tilt port deliberately.** `ctrl/k8s/.env.example` ships a value that
-is already in use, so copying it unchanged puts two projects on one port:
+The cluster takes the overlay's folder name and the context becomes
+`kind-<name>`, so there is nothing to edit for either. Replace the two example
+components under `k8s/base/`, and add your images and resources to the
+overlay's `Tiltfile`. Check the manifests before `kind` spends minutes on anything
+— this renders the whole tree without a cluster and catches a broken patch
+immediately:
 
 ```bash
-grep -h '^TILT_PORT=' ~/wdir/semester/*/ctrl/k8s/.env 2>/dev/null | sort
+kubectl kustomize local/myenv/k8s/overlays/dev
 ```
 
-Choose a free one in `10300–10399` — the range ALL reserves in
-`projects/index.json` under `policy` — avoiding `10350`, which is Tilt's own
-default. Currently taken: `nvi` 10330, `unt` 10340, `mpr` 10360, `mlv` 10370,
-`eth` 10380, `lng` 10390. This is the Tilt *web UI* port, not a service port;
-each project owns its own service ports separately. The scaffold ships it blank
-on purpose, so there is nothing to collide with until you choose.
-
-The scaffold's `ctrl/k8s/` is the same shape as every other project here, and it
-builds as shipped:
-
-```
-kind-config.yaml       one node; gateway NodePort 30080 -> hostPort 8080
-base/                  namespace, configmap, app (Deployment + Service)
-overlays/dev/          promotes the app Service to NodePort 30080
-```
-
-Check it before `kind` spends minutes on anything — this renders the whole tree
-without a cluster and catches a broken patch immediately:
-
-```bash
-kubectl kustomize ctrl/k8s/overlays/dev
-```
-
-The workload is an nginx placeholder so a fresh copy reaches something that
-answers; replace it. Keep `30080` in step between the overlay patch and
-`kind-config.yaml`'s `containerPort` — the hostPort is this project's to pick.
-Reachability is a plain kind port mapping: no ingress controller and no MetalLB.
-Caddy maps `<slug>.local.ar` onto the host port (`~/wdir/semester/ppl/local/Caddyfile`),
-with `*.local.ar` resolving to 127.0.0.1 through dnsmasq. That is the whole chain.
-
-**For `ctrl/Tiltfile`, copy rig's** rather than a live project's. rig ships one
-that derives its cluster, context, ports and manifest directory from
-`ctrl/ports.sh active` instead of hardcoding a slug, and carries a catalogue of
-the blocks every project here ends up needing. Copying from `unt` or `nvi` is
-what the estate did until now, and it is why the same Tiltfile preamble exists
-in six places with the slug typed in by hand five times each.
-
-> **Two things in this document disagree with rig and are not settled.** It
-> mandates Tilt ports in `10300–10399`, while rig derives a block from the
-> directory name at `20000+` so copies cannot collide — a rig-managed project
-> takes rig's. And it names `ctrl/k8s/.env.example`, which is the `broad`
-> scaffold's layout; rig's is `ctrl/.env.example`. Both are this document
-> describing the house scaffold from inside rig's tree.
+If the overlay is to be versioned, make `local/myenv` a repository of its own (rig
+never tracks it), or keep it anywhere else and name it by path.
 
 
 ## Run it
@@ -266,20 +207,9 @@ make kind-up      # idempotent create, then selects the context
 make tilt-up      # context + your assigned port
 ```
 
-`tilt-up` passes `--context kind-<slug>` every time, which is the point of going
+`tilt-up` passes `--context kind-<name>` every time, which is the point of going
 through `make` at all: tilt cannot deploy into whichever cluster you last looked
 at.
 
 `make tilt-down` and `make kind-down` close the loop, and `make kind-reset` is
 delete-and-recreate for when a cluster wedges.
-
-
-## Register it
-
-The project exists; now it is findable. Add an entry to
-`~/wdir/semester/all/projects/index.json` and write its `projects/<slug>.md` beside the
-others. Structured fields in the index, prose in the markdown.
-
-Putting it on the CI server and deploying it is `ppl`'s half, and it starts at
-`~/wdir/semester/ppl/ctrl/init-repo.sh` — gitea remote, then Woodpecker. That is a
-different document.