mariano/soleprint
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

simpler check and deps messages

Browse Source
This commit is contained in:
buenosairesam
2026-09-17 15:01:48 -03:00
parent 1dc9d38c80
commit 565cecfb50
49 changed files with 1442 additions and 1426 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
rig/docs/notes/Dockerfile.deps.md Normal file
View File

@@ -0,0 +1,28 @@
# ctrl/Dockerfile.deps
## Purpose
The toolchain installer image. It does NOT run the cluster — it installs a toolchain onto the host and gets out of the way.
This exists to kill a bootstrap paradox: a plain bash installer needs curl, jq and sha256sum to already be present, and a minimal Debian has none of them. It carries its own toolchain, so the only host prerequisite is Docker.
## Variants
Two variants from one file:
```
docker build -f ctrl/Dockerfile.deps --target deps -t <slug>-deps .
docker build -f ctrl/Dockerfile.deps --target deps-full -t <slug>-deps:full .
```
`deps-full` bakes every pinned binary in at build time. `docker save` it and you have the whole installer as one file to carry into an air-gapped network.
## Packages
ca-certificates + curl: fetch and verify. graphviz + python3: render diagrams and validate the arch model, so the host never needs an apt package.
docker-cli, NOT docker.io: we only ever talk to the host's daemon through the mounted socket, and under `--no-install-recommends` the docker.io package ships docker-init without the actual `docker` binary.
## The installer is the standalone kit
The installer is the generated standalone kit, not deps.sh plus the files it reads. A kit is one file with its pins frozen in and is proven to run with nothing else from rig present — which is exactly what an image needs, and `make standalone` keeps it current. Pins are the same in every profile's kit.

43
rig/docs/notes/Dockerfile.example.md Normal file
View File

@@ -0,0 +1,43 @@
# ctrl/Dockerfile.example
## Naming
EXAMPLE — a component image. Copy, rename, replace. Named like the manifest it feeds and the resource it becomes:
```
ctrl/Dockerfile.api -> image <cluster>-api -> image: in k8s/base/api.yaml
```
That image string is the ONLY thing connecting the three. Nothing checks it; a typo shows up as a pod stuck in ImagePullBackOff pulling from the public index, which reads like a network problem and is not one.
## COPY paths are repo-root relative (the one that catches everyone)
The Tiltfile passes two paths with DIFFERENT bases, in adjacent arguments:
```
context='..' the REPO ROOT (the Tiltfile is in ctrl/)
dockerfile='Dockerfile.api' relative to the TILTFILE, so ctrl/Dockerfile.api
```
So every COPY is resolved against the repo root, NOT against the Dockerfile's directory. A file sitting right beside it is still reached as `ctrl/`:
```
COPY ctrl/nginx.conf /etc/nginx/conf.d/default.conf # correct
COPY nginx.conf /etc/nginx/conf.d/default.conf # fails — no such file
```
Nothing warns you. The build just cannot find a file that is visibly there.
## Dependency layer
Dependencies first, in their own layer: they change far less often than the code, so a source edit does not reinstall them on every rebuild.
## live_update
The sync in the Tiltfile's `docker_build` must land where this image expects it:
```
live_update=[sync('../api', '/app/api')]
```
matches `COPY api/ ./api/` with `WORKDIR /app`. If the two disagree, Tilt syncs into a path nothing reads and the container keeps serving the built copy — edits appear to do nothing, with no error anywhere.

56
rig/docs/notes/Makefile.md Normal file
View File

@@ -0,0 +1,56 @@
# Makefile
## Shape and config layers
Thin control Makefile: few targets, and the subcommand is an argument rather than a second target: `make cluster down`, not `make cluster-down`.
```
make check is this machine ready? (never changes anything)
make deps install the toolchain
make cluster up cluster + registry + addons (ports derive by themselves)
make tilt / docs work on it, read about it
```
The logic lives in the scripts, never here: `make cluster up` -> ctrl/cluster.sh up.
Config layers, weakest first: built-in defaults < ctrl/versions.env (pinned toolchain) < ctrl/env.d/<profile>.env (optional) < ctrl/.env (local, gitignored) < the environment. So `make cluster up PROFILE=<name>` beats them all. See [config.md](config.md).
Start with: `make check && make deps && make cluster up`
## FACTS
Identity follows the FOLDER NAME, so this directory can be copied elsewhere, renamed, and run as a separate environment with no edits. ctrl/.env overrides it when you want a name that differs from the directory.
Asked once, of ctrl/ports.sh, which resolves it through lib/config.sh:
```
CLUSTER KUBECONTEXT HTTP HTTPS TILT REGISTRY MANIFESTS_DIR
```
Read positionally, so the order is a contract; ctrl/selftest.sh pins it.
This used to be sed over ctrl/.env plus a slug computed in the Makefile, which is a SECOND derivation of values lib/config.sh already owns, and the two could disagree about the port after `ports.sh persist`, or about the name for any directory whose sanitised form differs from its raw one. One source now; the Tiltfile reads the same line.
## CLUSTER / KCTX fallback
The fallback matters: ports.sh sources config.sh, and if a profile or .env is broken it exits non-zero. Losing the cluster name would send --context to the wrong place, so fall back to the folder rather than to empty.
## ARGS as .PHONY
Words after the target become the script's subcommand; each gets a no-op rule so make does not treat them as goals. They are also marked PHONY, because some of those words name real directories. `cfg`, `ctrl`, `docs`, `gen` and `init` all exist at this level, and make considers a target that is an existing directory already built, so `make build ctrl` ran the build and then printed "make: 'ctrl' is up to date". The empty rule is not enough on its own; only .PHONY stops make consulting the filesystem.
## tilt: --port guard
--port is only passed when TILT_PORT resolved. It normally does, since FACTS asks ports.sh, but ports.sh can fail on a broken profile, and without the guard tilt receives a bare `--port` with no value and fails on the flag rather than on anything real. Tilt's own default is 10350, which is the number every project on this machine is trying not to collide on, so falling back to it silently is worse than not passing the flag.
The Tiltfile asks ports.sh for the rest itself (cluster, registry and where the manifests are), so nothing needs passing here beyond what tilt's own flags require.
## Aliases (kind-up, tilt-up, ...)
Aliases, not a second implementation: each one calls the same script the canonical target does.
The header argues for `make cluster down` over `make cluster-down`, and that still holds *within* the Makefile. But rig is one repo among several on the same machine, and every other one answers to kind-up / tilt-up. Muscle memory spanning six projects beats internal tidiness in one, so both spellings work.
`cluster list` and `cluster free` have no hyphenated twin on purpose: they are rig's own, with nothing to be consistent with.
Nothing outside the Makefile reads these names: the script is `ctrl/cluster.sh` and it takes the verb. So rename them, delete the ones you never type, or add the spelling your own projects use. An alias is two lines, and adding one costs nothing but a line in .PHONY.

50
rig/docs/notes/Tiltfile.md Normal file
View File

@@ -0,0 +1,50 @@
# ctrl/Tiltfile
## Purpose and ownership
This file ships with rig and works unedited: rig's own k8s/base already boots, so `make tilt` comes up with a running cluster and no editing at all. What it deploys is two EXAMPLES — replace them, and add your own images and resources in the two marked sections near the bottom. The catalogue after them has the blocks to paste, with the parts that are easy to get wrong already commented.
rig supplies this file; it does not own it. Nothing in rig reads it back, and nothing here is regenerated — edit it freely, the way you would edit k8s/base/example-mock.yaml. rig owns the machine, you own the workload.
## Nothing hardcoded to this directory
Nothing in the Tiltfile is hardcoded to this directory, deliberately. Every other project here writes its slug into the Tiltfile five or six times by hand, so a copy of the project deploys into the original's cluster until someone remembers to edit all of them. A rig is meant to be copied and renamed, so it asks instead.
## Who we are, and on which ports
One question to rig, answered by ctrl/ports.sh, which resolves it through lib/config.sh — the same path every other rig script takes. That is the point: the cluster name is NOT the bare directory name (it is lowercased and reduced to a DNS label), and the ports honour anything pinned in ctrl/.env. Recomputing either of those here in Starlark is how two copies end up disagreeing about which cluster they are talking to.
## Where the manifests live
rig's own manifests are the default; point MANIFESTS_DIR in ctrl/.env at an overlay versioned somewhere else and rig stops owning them — see k8s/README.md. Real manifests usually change on a different cadence, by different people, under different review.
The value is REPO-ROOT relative, because that is the root everything else in rig is expressed against. The Tiltfile runs in ctrl/, so prefix rather than assume: `'../' + 'ctrl/k8s/overlays/dev'` and `'../' + '../platform/overlays/dev'` are both right, where stripping a leading `ctrl/` would only fix the first.
## Refuse to deploy into the wrong cluster
Tilt snapshots the kubectl context at startup, BEFORE parsing this file, so it cannot be switched from here — only refused. `make tilt` passes --context for you; the guard catches a bare `tilt up` after some other project moved the global context.
## Images go to this environment's own registry
Fail closed. Tilt can usually infer the kind registry on its own, but "usually" is an inference, and when it misses, an unqualified name like `app` quietly means docker.io/library/app — a push to the public index instead of the registry two lines away. rig runs that registry; name it.
## Catalogue
The catalogue holds the shapes that recur across every project here, with the reasoning kept next to them. They are comments so the file runs as-is.
## Catalogue: build an image
The one genuinely non-obvious thing in the whole corpus: `context` and `dockerfile` are relative to DIFFERENT directories, in adjacent arguments, and nothing warns you.
- `context=` the REPO ROOT — the Tiltfile is in ctrl/, so `'..'`
- `dockerfile=` relative to THIS file — so `'Dockerfile.api'` is ctrl/Dockerfile.api
Every COPY inside those Dockerfiles is therefore repo-root relative: a file sitting BESIDE the Dockerfile is still reached as `COPY ctrl/nginx.conf`.
## Catalogue: reload the gateway when its config changes
A Caddyfile arriving via configMapGenerator with disableNameSuffixHash does NOT roll the pod — the ConfigMap name never changes, so nothing tells the Deployment anything happened. Without the `gateway-reload` local_resource you edit the routes and watch nothing take effect.
## Catalogue: reach a service directly, bypassing the gateway
For a DB client or an admin UI. Prefer routing through the gateway: host ports are a single shared namespace across every project on this machine, which is why rig derives a block per environment in the first place. If you do need one, take it from this environment's own block rather than picking a number.

73
rig/docs/notes/addons.md Normal file
View File

@@ -0,0 +1,73 @@
# ctrl/addons.sh and ctrl/addons/*.sh
## addons.sh
Each addon is its own idempotent script in `ctrl/addons/` — adding one is adding
a file, not editing a dispatcher.
## airflow.sh
Airflow needs a metadata database before it will start at all, so the script
refuses rather than rolls a pod that will CrashLoopBackOff while the real problem
(postgres missing from `ADDONS`) stays invisible in the logs.
One pod on `standalone`, matching the compose cabinet: migration, admin user,
scheduler and webserver in a single container. The official chart's five
deployments model an installation; switching this on means wanting pipelines.
## cert-manager.sh
In a regulated estate almost everything is TLS, so the interesting question
during onboarding is "does this service present a cert my client trusts" — not
"can I reach a public ACME server". A local CA answers that offline, which is
also what makes the air-gapped profile usable.
## metallb.sh — why it matters
Real manifests use LoadBalancer, because a real cluster has one. On a bare kind
cluster those Services sit at `EXTERNAL-IP <pending>` forever with no error
anywhere — the deployment looks fine and simply is not reachable. Without MetalLB,
every such Service has to be edited to NodePort, which means the local manifests
stop matching the ones being modelled.
The address pool is derived from the kind Docker network at install time, not
hardcoded: Docker picks that subnet, it differs between machines, and a pool
outside it is silently unroutable.
## metallb.sh — waiting for the controller
`kubectl wait` on a selector errors out immediately when nothing matches yet, and
right after apply the ReplicaSet has not created the pod — so it loses a race it
looks like it should win. `rollout status` waits for the Deployment itself and
handles the not-yet-created case.
## metrics-server.sh
kind nodes serve kubelet metrics over a self-signed cert, so the standard
manifest never becomes ready without `--kubelet-insecure-tls`. That is fine here
(it is a local cluster) and is the single most common reason metrics-server sits
at 0/1 on kind.
## postgres.sh — cabinets
A cabinet is a public service dropped into the environment as-is — the upstream
image, unmodified, reachable at a known address. `postgres.sh` is the cluster
half of it; the compose half is a `service.yml` beside a `cabinet.json`. The
declaration is made once and both paths read it, so nothing is remembered twice.
## postgres.sh — plain manifests, one replica
Plain manifests rather than a helm chart, matching the other addons: a chart repo
is a network dependency, and the offline example profile exists precisely so
there is a path with none. The image is pinned in `ctrl/versions.env` and can be
preloaded into a local registry like every other image here.
One replica on a PVC. This models a dependency for local work, not a
highly-available database, and pretending otherwise on a kind node would be a
more elaborate lie rather than a more useful one.
## redis.sh
Cache, and the broker anything queue-shaped runs on. No persistence: a broker
that loses its queue on restart is the honest local model, and a PVC here buys
nothing but a volume to clean up.

44
rig/docs/notes/check.md Normal file
View File

@@ -0,0 +1,44 @@
# ctrl/check.sh
## Purpose
Readiness check: is this machine ready to run rig?
It reports and instructs; it never silently fixes anything. Everything it finds is either already fine, or something a human has to decide on.
Runs ctrl/deps.sh host detection in a container when Docker is the only thing installed, or directly when the toolchain is already present. Then adds the checks that need this repo's config: profile sanity, CA trust, port clashes.
## memory
A profile on a box that is already full is the most common first failure, and it presents as pods stuck Pending rather than anything that says "memory". The check warns; it never blocks. Whether to try anyway is the user's call.
## mb_of
MEMINFO and OVERCOMMIT_FILE exist only so the tight and does-not-fit branches can be exercised against another machine's real numbers; in normal use they are the kernel's own files.
## NODE_MB
NODE_MB (what one node costs) comes from load_config (lib/config.sh), where its measurement is recorded. It lives there, not here, because the memory tool and every standalone kit need the same number: a copy of it is how rigmini.sh came to say 2 GB per node long after rig had measured 800 MB.
## container_mb
Every running container's working set in MB, tagged with the kind cluster it belongs to ('-' when it is not kind). docker stats reports usage minus page cache, which is what actually competes: cache is handed back under pressure. Counting only kind would hide the usual culprit on a managed workspace, where the memory is held by other containers entirely.
## ours_mb / still_mb
Once this environment's own cluster is running, its real footprint is already out of MemAvailable and the per-node estimate stops being relevant. Subtracting the measurement from the estimate would count the same memory twice, and a running cluster that happens to sit under 800 MB would still "need" the gap.
## ports: our own cluster
A port held by THIS environment's own cluster is not a clash; it is the thing working. Reporting it as a problem every time the cluster is up would train people to ignore this section, which is the opposite of the point.
The ports are extracted with a second grep rather than `tr -d ':->'`: in tr, ':->' is the character RANGE ':' to '>', which does not contain '-', so the trailing dash survives and nothing ever matches.
## Compact by default
`make check` prints one line per question — host, toolchain, and for this rig: cluster, memory,
ports, registry, addons — and adds detail only where something needs attention (`!` lines, the
"held elsewhere" list when memory is tight, the clashing port). `make check all` prints every fact,
as the full report did before 2026-09-17. `deps.sh detect all` is the same switch for the host part,
so the standalone `rigdeps.sh detect` is short too. Changed because the long report buried the few
lines that mattered.

15
rig/docs/notes/cluster.md Normal file
View File

@@ -0,0 +1,15 @@
# ctrl/cluster.sh
## Why list and free live here
`list` and `free` live in `cluster.sh` rather than in a separate script because a
near-identical second name (cluster / clusters) is a trap — you reach for one and
get the other. One target, one file, unambiguous subcommands.
## Idempotent means convergent
"Idempotent" here means convergent, not "exits early if the cluster exists".
That distinction matters: an interrupted first run can leave a cluster created
but not finished, and returning early on the re-run would strand it there. The
create step is conditional; every step after it always runs, and each one is
individually idempotent.

99
rig/docs/notes/config.md Normal file
View File

@@ -0,0 +1,99 @@
# ctrl/lib/config.sh
## Purpose and precedence
The ecosystem convention is that scripts are standalone with no shared log library, and that still holds. This file is not a logging lib; it is the single definition of how the config layers compose, which every script has to agree on exactly. Precedence, weakest first:
```
built-in defaults in load_config; fill only what nothing else set
ctrl/versions.env pinned toolchain + image digests (committed)
ctrl/env.d/<profile> addons, registry (OPTIONAL, examples ship as *.env.example)
ctrl/.env machine-local values and secrets (gitignored)
the caller's env `make cluster up PROFILE=<name>` (always wins)
```
That last rule is why this is more than a few `source` lines: .env sets PROFILE, so without snapshotting it would silently override the PROFILE the user just typed on the command line.
Run from ctrl/.
## CONFIG_OVERRIDABLE
Values a user can reasonably override per-invocation. Anything set in the environment when load_config runs is restored after the files are read. NODES is deliberately NOT here: it is read back out of the kind config, so the file is the one place that decides it.
REGISTRY_PORT and MANIFESTS_DIR were missing here while ctrl/.env set them, so the caller's env silently LOST to the file for those two, breaking the one precedence rule the header states. Both are now listed; the other twelve are unchanged.
## default_cluster_name
The containing folder's name, reduced to something kind accepts as a cluster name (a DNS label: lowercase alphanumerics and dashes). Run from ctrl/, so the repo root is the parent.
## derive_port_base
Base of this environment's 10-port block. cksum is used rather than $RANDOM or bash hashing because it is POSIX and returns the same value on every machine, which is what makes the block reproducible instead of merely unique.
## load_config: RIG_PORTABLE
RIG_PORTABLE skips the machine-local layer. config_snapshot sets it, so a generated standalone kit never carries this machine's .env, which holds local values and, by its own description, secrets.
## load_config: profiles are optional
A profile is an optional overlay, never a prerequisite. rig assumes no configuration: with no profile named, or no env.d/ at all, it runs on the built-in defaults. What IS an error is naming a profile that does not exist, because a typo must not quietly fall back to something else.
## load_config: identity follows the folder
Identity follows the FOLDER, so copying this directory somewhere else and renaming it yields a distinct environment with no further edits. Without this, two copies would share one cluster and `make cluster down` in either would destroy the other's.
## load_config: host ports
Host ports are a single shared namespace, so unlike the cluster name they cannot just follow the directory; they have to be spread out. Anything already set (ctrl/.env, a profile, the command line) wins; only the gaps are filled. See [ports.md](ports.md) for the reasoning.
## load_config: MANIFESTS_DIR
Where the workload's manifests live, repo-root relative. Defaulted here so it is always resolved rather than sometimes-set: it is the seam that lets the real manifests be versioned away from the installer, and a consumer should not have to know whether anyone filled it in. See k8s/README.md.
## load_config: NODE_MB
What one node costs, measured rather than guessed. On 2026-09-11 a minimal control-plane node ran at 620 MiB idle and ~728 MiB with a small mock, plus 16 MiB for the local registry: ~745 MiB of working set. 800 rounds that up, and agrees with the 800 MB observed independently on a larger rig. Worker nodes carry no etcd or apiserver and are lighter, so for a multi-node shape this errs high. It is the cluster alone: whatever you deploy comes on top.
It is set here rather than in check.sh because the memory tool and every standalone kit need the same figure.
## render_kind_config
Renders the kind config to stdout. sed rather than envsubst: envsubst is gettext-base, absent from a minimal Debian, and Docker is meant to be the only prerequisite. The variable list is explicit so a template cannot quietly start depending on something the caller does not set.
hostPath entries are resolved by the HOST dockerd, so HOST_WORKDIR must stay a host path even when this runs inside the installer container.
## What a standalone kit needs to know
The kit generator (ctrl/standalone.sh) asks these questions so that it never has to know how configuration is stored. Where profiles live, which files are layered and what is derived are config.sh's business and can change freely; the generator only calls these functions.
## config_profiles
Every configuration rig can be run as, one per line: each profile file, or, when there are none, `default`, the built-in configuration load_config uses when no profile is named. Never empty, because rig never needs a profile.
## config_snapshot
The resolved configuration, as `declare -p` lines: exactly what load_config leaves behind, minus the machine-local layer. A kit freezes this in place of load_config, so it carries rig's decisions and not this machine's secrets.
```
config_snapshot <profile> that profile, as any machine would resolve it
config_snapshot --current what THIS machine runs: every overridable key as
resolved here, handed back in as if typed on the
command line, over the same portable resolution.
Values derived from those choices follow them;
anything else the local layer set (credentials)
is not carried. config_left_out names it.
```
Found by difference, not by a list: whatever load_config sets today, it sets. A list here would be one more place to forget a variable.
## config_left_out
What an export of this machine's configuration does NOT carry, by name only: keys the machine-local layer sets that are not choices a caller may override. They are this machine's own (registry and mirror credentials, mostly), so the target has to be told to supply them. Values are never printed.
## config_freeze
A replacement for load_config with a resolution frozen in (a profile, or --current; see config_snapshot), printed as a function definition for a standalone kit to carry. The generator embeds whatever this prints and interprets none of it, so what "frozen" means stays rig's decision.
It keeps load_config's one stated rule: the caller's env wins for anything in CONFIG_OVERRIDABLE. A kit therefore behaves like rig (`OUT_BIN=... rigdeps.sh` still works) rather than like a copy with everything pinned.
What freezing does give up, knowingly: values DERIVED from an overridable one are fixed at generation. Override CLUSTER and the ports stay the ones derived for the original name. Re-deriving would mean carrying the layering itself, which is exactly what a kit exists not to need.

158
rig/docs/notes/deps.md Normal file
View File

@@ -0,0 +1,158 @@
# ctrl/deps.sh
## Purpose and safety
Toolchain installer: detect the host, install a pinned toolchain onto it, then report what it could not do.
It never runs the cluster, never uses sudo or apt, and writes only into `$OUT_BIN` (default `~/.local/bin`). Everything that would touch the host proper — systemd, inotify limits, `.wslconfig`, docker group — is REPORTED for a human to decide on, never performed. That is what makes it safe to run on a machine that already has a working setup.
## Usage
Normally via `make deps`, or directly:
```
deps.sh detect # report host facts only, change nothing
deps.sh list # the pinned versions
deps.sh verify [core|dev] # run what is installed and see if it works
deps.sh fetch [core|dev] [--to DIR] # download + verify into DIR
deps.sh install [core|dev] # detect, fetch, install, report
```
Tiers: `core` is kubectl + jq (talk to a cluster); `dev` adds kind and tilt. Default is dev.
## Container vs bare host
Runs both inside the installer container and bare on a host. Inside the container, host files are read through `$HOST_ROOT` (mount `/` as `:ro`); bare, it falls back to `/`.
Host FILES (`/etc/...`, `/mnt/c/...`) must be read through the mount. Kernel-level facts (kernel version, meminfo, inotify) are shared with the container, so the container's own view is already the host's.
## INVOKED_FROM
Keep the caller's cwd so a relative `--to` resolves where the user expects, not against `ctrl/` once we've moved.
## load_config
Pins arrive through `load_config` like every other setting, not by sourcing `versions.env` here. That is what lets `make standalone` freeze them into a one-file installer: configuration has exactly one way in.
## mb_of
A `/proc/meminfo` field in MB, 0 if the field is absent. `MEMINFO` exists so the tight and does-not-fit branches can be exercised against a real machine's numbers from somewhere else; in normal use it is always `/proc/meminfo`.
## require_amd64
The pins are amd64. Rather than download something that cannot execute and let it fail as "cannot execute binary file: Exec format error", say so here and hand over the commands that produce the right checksums.
## pkg_install_cmd
This never runs a package manager. It names one so the reported action is something you can paste, on the distro you are actually on — an apt line on Amazon Linux 2 is a wrong answer dressed up as help.
## require_linux
Windows outside WSL — Git Bash, MSYS, Cygwin — looks close enough to work and then fails in a pile of confusing ways: no /proc, no docker socket, none of the tooling. Detectable, so name it instead.
## detect: memory
In MB. Whole gigabytes lose nearly half a GB on exactly the machines where it matters: 1874 MB available used to print as "1 GB". Facts only — whether that is enough depends on the profile, which `check.sh` knows and this does not.
## detect: overcommit
How the kernel answers an allocation it cannot really satisfy. With 1 it always says yes and settles up later with the OOM killer, so a cluster that starts cleanly can still lose processes afterwards.
## detect_wsl: systemd
systemd is off by default in WSL, and the ingress/DNS paths that use a host service need it. Enabling it requires a Windows-side restart, which cannot be issued from inside the distro.
## watch_hostile_fs
Not a path check: `/mnt` is an ordinary mount point and an ext4 disk mounted there is perfectly fine. What matters is the filesystem. The Windows drives arrive as 9p (WSL2) or drvfs (WSL1); network and fuse mounts behave the same way. None of them deliver inotify events, so anything watching files goes quiet without saying why.
## detect_libc
tilt is the one binary here that needs a recent glibc. MEASURED, not guessed: tilt 0.37.6 on Amazon Linux 2 (glibc 2.26) fails with
```
/lib64/libc.so.6: version `GLIBC_2.34' not found (required by .../tilt)
```
which names a symbol rather than the problem. Amazon Linux 2 is a stock WorkSpaces bundle, so this is the likely case, not an exotic one. Report the version now; `verify` catches the actual failure after installing.
## detect_prereqs
What this script needs to do its own job. Reported here so `detect` answers "will install work?" instead of leaving you to find out one download in. Amazon Linux 2 ships without tar, which is exactly the surprise this catches.
## detect_docker
Reachability of the daemon is the real question, and the CLI is only how we ask it. When this runs inside the installer container, Docker necessarily exists on the host — otherwise nothing would be executing — so a missing CLI in there is an installer packaging bug, not a host problem.
The kind-node count check must be an `if`, not `[ ] && echo`: as the last statement in the function the latter returns 1 when the count is zero, and `set -e` then kills the caller. That is the fresh-machine case — no clusters yet — so the bug only ever shows up where it does most harm.
## fetch_tgz: --no-same-owner
Extracting as root would otherwise restore the uid/gid baked into the archive (some ship as uid 1001), leaving a binary the host user does not own.
## fix_ownership
The installer runs as root so it can reach the docker socket, which means everything it writes into a mounted volume lands root-owned and unusable from the host. Hand it back to whoever owns the mount point (the host user created that directory before mounting it).
kind writes the kubeconfig as root too; `fetch` hands that back as well when it's a mounted host directory rather than container-local state.
## Tiers (CORE_TOOLS, DEV_TOOLS)
Two tiers, because not every machine should get cluster tooling.
- `core` — kubectl, jq: talk to a cluster someone else runs. Nothing that creates one. Appropriate on a managed or corporate-issued machine where development tools are not wanted by default.
- `dev` — core plus kind and tilt: build clusters and hot-reload into them.
The split exists because "install the toolchain" is not one decision: on a managed workspace the right answer is kubectl and nothing else.
No helm: every addon installs with `kubectl apply -f <url>`, so nothing here has ever invoked it. Add it back the day something actually needs a chart.
ctlptl is `dev` rather than `core` for the same reason kind is: core is "talk to a cluster someone else runs", and ctlptl builds them. It earns its place because it is what wires a cluster to a local registry — without one, an unqualified image name resolves to `docker.io/library/<name>` and there is nothing structural stopping a push there.
docker-compose is `dev` for the same reason, and is here because the distro docker packages ship the daemon and CLI but frequently not the compose plugin — so `docker compose up` fails with "unknown command" on an otherwise working Docker, and nothing about that message names the missing piece.
## What is already on this machine (pin_of)
A tool already on PATH at its pinned version is left where it is. Without this, install downloads a second copy into `OUT_BIN` and then reports the first one as shadowed — noise, and wrong, when both are the same version. That is the normal state of any machine someone set up by hand, whatever directory they happened to choose.
## reported_version
Each tool spells the version question differently, and kubectl has to be told `--client` or it goes looking for a server to ask.
## version_matches
Matched as a whole version token, so 0.37.6 never matches 10.37.60, with the leading v optional either side: kind says v0.32.0, jq says jq-1.8.2, and tilt says v0.37.6 against a pin of 0.37.6.
Bash's own regex rather than grep, deliberately. grep is not the same program on every machine — some builds reject patterns that others accept — and a failed grep inside a count reads exactly like a zero.
## want / DEPS_ONLY
`DEPS_ONLY` narrows a fetch to the tools it names. Unset means the whole tier, which is what an explicit `deps.sh fetch` always gets: "download these into DIR" must not quietly skip something because this machine happens to have it. Only `install()` sets it, to what `detect_toolchain` found missing or mismatched.
## detect_toolchain: compose
compose is the one tool that is normally NOT a binary on PATH. It is a docker CLI plugin, so a machine where `docker compose` works perfectly has no `docker-compose` to find — and probing only PATH would report it missing and re-download a copy that is already there. That is the exact noise the version-aware skip exists to prevent, so ask docker instead.
## verify_tools
Installing into a directory that sits early in PATH silently replaces whatever the machine was already using — which on a shared or client machine can break unrelated work (kubectl more than one minor away from a cluster is the common one). Say so; never decide it for them.
Downloading a verified binary proves it is the right file, not that this machine can run it. On an old distro tilt fails here, with a linker error about a missing symbol, and finding that out now beats finding out during a first cluster build.
Output is not piped into `head`. With `pipefail` set, a tool that prints more than one line gets SIGPIPE when head closes the pipe, and the pipeline reports 141 — so a working kubectl was announced as "does not run here", with its own correct version string as the evidence. The first line is taken afterwards, from the string.
## install_compose_plugin
A copy in `OUT_BIN` only gives you `docker-compose`. That hyphenated form is the retired v1 spelling; every compose file written in the last few years assumes `docker compose`, which resolves plugins BY NAME out of a plugin directory. So the binary is fetched like any other and then linked, in your own home — no root, and nothing outside it.
If something else already owns that name — docker-desktop and some distro packages install a real file there — overwriting it would take the plugin away from whatever put it there, so say so and let the user decide.
## install
The plugin is linked only when compose was one of the things fetched: linking a binary that is already satisfied elsewhere on PATH would point the plugin at a copy rig did not install.
The "put OUT_BIN on PATH" advice is only worth giving when something actually landed in `OUT_BIN`. When every tool was satisfied elsewhere, `OUT_BIN` may reasonably be off PATH, and telling the user to add it would be advice to fix nothing.
## main: argument shift
Read the command, THEN shift — and shift only if there is something there. A bare `shift` with no positional parameters returns 1, and under `set -e` that ended the script before a single line was printed: running this with no arguments at all, the documented default, did nothing and said nothing.

14
rig/docs/notes/docs.md Normal file
View File

@@ -0,0 +1,14 @@
# 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.
## 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.

74
rig/docs/notes/env.md Normal file
View File

@@ -0,0 +1,74 @@
# ctrl/.env.example, ctrl/env.d/*.env.example
## ctrl/.env.example: header
Machine-local config. Copy to ctrl/.env (gitignored) and edit. The cluster SHAPE is an optional profile in ctrl/env.d/ — see the *.env.example there. The architecture MODEL lives in arch/<name>.json — not in .env either.
## ctrl/.env.example: CLUSTER
The kubectl context becomes kind-<CLUSTER>. LEAVE THIS UNSET unless you need a name that differs from the directory — it defaults to this folder's name, which is what makes the folder copyable: copy it, rename it, and you get a separate environment with no edits.
## ctrl/.env.example: host ports
LEAVE UNSET — they derive from the directory name so several environments coexist without negotiating (see ctrl/ports.sh). `make check` shows this environment's block; `bash ctrl/ports.sh persist` writes it into ctrl/.env so it stops being derived and becomes fixed. Set a value only to override.
## ctrl/.env.example: MANIFESTS_DIR
Where the application manifests live. The real ones are expected to be versioned separately from this installer — they change on a different cadence, by different people. Repoint this at their repo and rig stops owning them:
MANIFESTS_DIR=../platform-manifests/overlays/dev
## ctrl/.env.example: DEPS_SOURCE
Where the installer fetches the pinned binaries from.
- `upstream` — GitHub releases / dl.k8s.io (needs internet)
- `artifactory` — a generic repo; what a locked-down client usually allows
- `baked` — already inside the installer image; no network at all
## ctrl/.env.example: registry secrets
The registry mode comes from the profile (REGISTRY_MODE). REGISTRY_REMOTE_URL, REGISTRY_USER and REGISTRY_PASSWORD are the secrets it needs, required for mirror/remote.
## ctrl/.env.example: REGISTRY_CA_FILE
Corporate root CA, if Artifactory is fronted by an internal CA (it usually is). Trust has to reach THREE places and nothing does it for you: the host docker daemon, every kind node's containerd, and any in-cluster client. registry.sh handles the first two; check.sh reports when it's configured but not trusted. Symptom when missing: `x509: certificate signed by unknown authority`.
## env.d/*.env.example: profiles in general
EXAMPLE PROFILES. rig needs none of these: with no profile it runs on its built-in defaults (lib/config.sh). To use one, copy it to <name>.env in ctrl/env.d/ and name it — PROFILE=<name> in ctrl/.env, or on the command line. It then overlays the defaults; anything it does not set, they still supply.
## env.d/client.env.example
client — images through a pull-through cache of the corporate registry, with TLS and metrics addons. More nodes or port mappings: edit k8s/kind-config.yaml.tpl.
### Real ports (80/443)
Ports derive from the directory name by default (see ctrl/ports.sh), so several environments run side by side.
Opt in to the real ports only when this is the ONLY environment and nothing else owns :80. They fail to bind otherwise, and docker reports it as an opaque "failed to bind host port 0.0.0.0:80/tcp: address already in use" halfway through cluster creation. `make check` checks before you spend the time. Uncommenting also means only one environment can exist at a time.
## env.d/data.env.example
data — databases and a scheduler for an environment that needs them: postgres, redis and airflow, each an upstream image run unmodified.
Everything lands in the `data` namespace (DATA_NAMESPACE to move it), so `make cluster reset` on the app namespace leaves the databases alone.
Costs roughly 2-3 GB with airflow, under 1 without. Airflow's first boot runs the whole metadata migration, so expect a few minutes before it is ready.
### Postgres password
The password is not in the profile: postgres.sh generates one on first install and keeps it across re-runs, so re-running the addon never rotates the credential out from under whatever is already connected.
### Reaching the databases
Ports derive from the directory name by default — see ctrl/ports.sh. Reach the databases with port-forward rather than binding more host ports:
kubectl -n data port-forward svc/postgres 5432:5432
kubectl -n data port-forward svc/airflow 8080:8080
## env.d/offline.env.example
offline — air-gapped. Everything comes from a local registry that was loaded ahead of time; nothing reaches the internet. Pair with the deps-full image (DEPS_SOURCE=baked) so the toolchain install is offline too.
The heavier addons are left out to keep first boot viable.

23
rig/docs/notes/kind-config.md Normal file
View File

@@ -0,0 +1,23 @@
# ctrl/k8s/kind-config.yaml.tpl
## Why a template
The cluster: one node by default — add nodes or port mappings by editing the file, then `make cluster reset`.
It is a TEMPLATE rather than a plain kind-config.yaml because a rig is copied and renamed to make a second environment, and both the cluster name and the host port follow the directory. A checked-in literal would make every copy collide on both. ctrl/cluster.sh renders it with sed — not envsubst, which is gettext-base and absent from a minimal Debian, and rig's whole premise is that Docker is the only prerequisite.
## Substituted variables
Substituted by ctrl/cluster.sh: CLUSTER, NODE_IMAGE, HTTP_PORT, HOST_WORKDIR. The header comment names them without the `${...}` braces so that line survives the substitution.
## Node count
The node count is READ BACK from this file by lib/config.sh, so this YAML is the source of truth for it — there is no second place to update.
## containerdConfigPatches
Point containerd at a certs.d directory. registry.sh drops per-host hosts.toml files in there afterwards, so switching registry mode never requires recreating the cluster.
## extraPortMappings
One NodePort bridged to the host; an in-cluster gateway owns it. There is deliberately no ingress controller — they pin a narrow window of k8s versions, and running a trailing-edge control plane is the point.

96
rig/docs/notes/mem.md Normal file
View File

@@ -0,0 +1,96 @@
# ctrl/mem.sh
## Purpose
How much memory this machine will actually give you before something dies. This is rig's memory tool, and the standalone rigmini.sh is generated from this file.
There are two numbers and they are rarely the same. `status` reports what the machine ADVERTISES and what is quietly capping it. `push` finds what it will SURVIVE, by allocating until it stops. `all` does both and weighs the result against what this profile's cluster needs.
The gap between them is the whole reason this exists. Under WSL the cap lives in .wslconfig; in a container or a managed workspace it is a cgroup limit, and there /proc/meminfo reports the HOST's memory while the kernel kills you at a fraction of it. A script that only read MemTotal would confidently report 32 GB on a box that OOMs at 2.
Runs on native Linux and under WSL. On WSL the memory you see is a VM allocation that can be raised, and the commonest failure is raising it without restarting, so status compares what .wslconfig says with what actually booted.
It reports and instructs. It never raises a limit, frees anything or installs a package. The one write it can make is `backup`, which copies .wslconfig beside itself, so that `restore` has something to put back after a hand edit.
Usage:
```
mem.sh status what it has, what caps it
mem.sh push [--to GB] [--to-oom] climb until it stops
mem.sh all [--budget GB] both, then the verdict
mem.sh backup | restore .wslconfig, WSL only
```
## require_linux
Windows outside WSL (Git Bash, MSYS, Cygwin) looks close enough to work and then fails in a pile of confusing ways: no /proc, no docker socket, none of the tooling. It is detectable, so name it instead.
## CG_MAX_FILE / CG_CUR_FILE
Where a cgroup records this cgroup's own limit and usage. Set once by find_cgroup, because every later reading needs both, and hunting for the files on each call would be the slow part of the poll loop.
## find_cgroup
Inside a container the cgroup namespace makes the top of the tree BE the container's own cgroup, so the unqualified path is already the right one. On a host it is the root cgroup, which is never limited; hence the second attempt via /proc/self/cgroup, which names the slice this shell is in.
## cgroup_cap_mb
Returns the cap in MB, or "" when there is none worth reporting. cgroup v2 spells unlimited "max"; v1 spells it as a number near 2^63, which is why this compares against MemTotal rather than testing for a magic value. A "limit" above the machine's own memory is not a limit, however it is written.
## headroom_mb
How much room is left RIGHT NOW, from whichever accounting actually governs. In a capped container /proc/meminfo describes the host and is worse than useless for this: it would report tens of gigabytes free on a box that is one allocation from being killed.
## wslconfig_path
/mnt/c/Users can hold several real accounts (a renamed login leaves the old directory behind), so picking the first alphabetically is a coin toss. Ask Windows, then fall back to whichever profile actually owns a config.
## status: overcommit
overcommit_memory=0 is the default heuristic: a large allocation is granted on a guess, and the reckoning arrives later as an OOM kill rather than as a failed malloc. It is why `push` touches every page it asks for.
## status: WSL
WSL keeps its cap on the Windows side, in a file this shell can read but not usefully apply: the change costs a full VM restart. Report it, and report the commonest mistake, which is editing it and not restarting.
## backup
Backups are timestamped and never overwritten: a backup that can destroy itself on a second run is not a backup.
## restore
Newest is the right default (undo the last edit), but if you backed up *after* editing, the state you want is older. The rest are shown so a no-op restore is obviously a no-op rather than a mystery.
## allocator
The child allocates and stops itself; the parent only watches. That split is the point: under --to-oom the allocating process is expected to be killed, and something has to survive to say how far it got.
### OOM score
The child raises its own OOM score to the maximum so the kernel picks THIS process first. Raising needs no privilege (only lowering does). Without it, the kernel is free to choose your shell, your ssh session or dockerd; on a box you are still using, that is not an acceptable coin toss.
### Writing straight into the array element
Each chunk is written STRAIGHT INTO the array element (`printf -v "arr[$i]"`). The obvious spelling, building one chunk and `arr+=("$chunk")`, costs three copies per step, not one: the template stays resident, expanding "$chunk" makes a temporary word, and the append makes the element. A 128 MB step then needs 384 MB transiently, and on a small box it is killed on the first append while reporting a third of the true ceiling.
printf -v into a subscript also means every page is written, so it is resident rather than merely promised: the only kind of allocation that measures anything under heuristic overcommit.
### First swap
Worth calling out separately from the ceiling: this is where the box stops being fast and starts being unusable, which for a scheduler is a different and earlier problem than being killed.
## push: step size
A step is worth about a sixty-fourth of the ceiling: enough resolution to find the edge, few enough lines to read, and small enough that the transient cost of one allocation never dominates a small box. A fixed size cannot do all three: 128 MB is fine on 16 GB and absurd on 512 MB.
## push: floor
Stop with a cushion rather than riding it to the kill. How big a cushion depends on what it is protecting. Under a cgroup cap, running out kills only this container's own processes, so it need cover no more than the shell that prints the result, and a 512 MB cushion on a 1 GB box would halve the answer. On a host there is everything else to protect, and the OOM killer does not promise to pick the process that caused the problem.
## push: Ctrl-C
INT kills the child and lets the summary print anyway, so an impatient Ctrl-C still tells you how far it got and, more importantly, still gives the memory back.
## push: claimed vs. measured
The gap between the claim and the measurement is the finding, but only when the BOX chose where to stop. An empty $stop means the child was ended rather than deciding to end; anything else (--to, the floor) is a stop we asked for, and flagging those as short of the ceiling would put a warning on every deliberately small run.

32
rig/docs/notes/ports.md Normal file
View File

@@ -0,0 +1,32 @@
# ctrl/ports.sh
## Why each environment gets a port block
New versions of a system mean new clusters on ONE machine, not new machines. Cluster name, kubectl context, registry container and image tag already derive from the directory name, so two copies never collide there, but host ports are a single shared namespace and would.
The block is derived from the directory name: stateless, stable, and requiring no coordination between copies that know nothing about each other.
```
base = 20000 + (hash(slug) % 200) * 10
+0 HTTP +1 HTTPS +2 TILT +3 REGISTRY (+4..9 reserved)
```
20000+ deliberately avoids the ports something is already likely to hold: 80, 443, 3000, 5432, 8000, 8080.
Derivation is a default, not a decision. On first use the resolved block is written into ctrl/.env, so it becomes pinned, visible and editable rather than a number that appears from nowhere. Anything already in ctrl/.env wins.
## active
The resolved facts a consumer outside bash needs, machine-readable:
```
CLUSTER KUBECONTEXT HTTP HTTPS TILT REGISTRY MANIFESTS_DIR
```
Identity and ports together, because they are one fact set: both derive from the directory name so that copies never collide. A consumer needs all of them or none, and fetching them separately is how two end up disagreeing. MANIFESTS_DIR rides along because the one consumer that needs the addressing is the one that needs to know what to deploy.
Space-separated, so MANIFESTS_DIR must not contain spaces. Everything else in rig already assumes that of paths; kind, docker and kubectl all do.
`derive` answers a DIFFERENT question (what the directory name alone implies) and deliberately ignores ctrl/.env. Configuring anything from it would silently contradict the rule that "anything already in ctrl/.env wins". `active` is what anything downstream should read.
Why this exists at all: the cluster name is not the bare directory name. default_cluster_name() lowercases it and replaces every character outside [a-z0-9-], because it has to be a DNS label. Re-deriving that in another language is how a copy in `My_Project/` ends up guarding the wrong context.

41
rig/docs/notes/registry.md Normal file
View File

@@ -0,0 +1,41 @@
# ctrl/registry.sh
## Registry modes
Registry plumbing. This is the seam — not a tool. Four modes, selected by
`REGISTRY_MODE` in the active profile:
- **none** — Tilt builds straight into the node. No registry at all, and so no
guard against an outward push: an unqualified image name means
`docker.io/library/<name>`, and only Tilt's kind detection stands between that
and a real push. Throwaway use only; every profile here now defaults to `local`
instead.
- **local** — a `registry:2` container wired into the cluster.
- **mirror** — the same container, but configured as a pull-through cache of the
corporate registry. This is what a locked-down client actually looks like:
images originate from corp, you don't hammer it, and you keep working when the
VPN drops.
- **remote** — no local container; pull straight from the corporate registry
using an imagePullSecret.
## Why a script rather than ctlptl
Deliberately a script rather than a tool. ctlptl collapses the `local` wiring
into one line, but its Registry spec only accepts name/port/image/listenAddress —
there is no way to set `REGISTRY_PROXY_REMOTEURL`, so it cannot express `mirror`
at all. Keeping the seam here is what keeps the corporate registry swappable.
## CA trust (install_ca_into_nodes)
A corporate registry is almost always fronted by an internal CA, and trust has to
reach three separate places. Nothing does this for you, and the symptom when it's
missing is an opaque:
x509: certificate signed by unknown authority
1. the host docker daemon — `/etc/docker/certs.d/<host>/ca.crt` (needs root)
2. every kind node's containerd — nodes do NOT inherit host trust
3. anything doing HTTPS from inside the cluster, in its own trust store
`registry.sh` handles (2) because it's ours to handle. (1) is reported by
`check.sh` since it needs root. (3) belongs to the workload.

67
rig/docs/notes/selftest.md Normal file
View File

@@ -0,0 +1,67 @@
# ctrl/selftest.sh
## Purpose
What rig has settled, written down as assertions.
These are documentation that runs. Each check is ONE decision that has already been made, with the reason above it: not coverage, and deliberately not an exhaustive sweep of use cases. rig's own index says a rule without its reason gets overridden the first time it is inconvenient; a rule nobody can restate is worse. So the test says what was decided, and failing it should read as "you are about to undo this" rather than "something broke".
Scope, on purpose:
- No cluster, no docker, no network. It must be cheap enough to actually run.
- It asserts about RIG. `make check` asserts about the MACHINE and never fails; this exits 1, the way `make standalone check` does.
- What actually deploys is not testable here. `tilt ci` stays a manual step.
## rig needs no profile
rig assumes no configuration. A profile is an overlay on built-in defaults, so a rig with no `env.d/` at all must resolve, report, and still generate a kit. Naming a profile that does not exist must still be an error, because a typo that silently fell back to the defaults would be worse than a failure.
## the ports.sh active contract
`ports.sh active` is read POSITIONALLY by two other files: the Makefile takes `$(word 2)` and `$(word 5)`, the Tiltfile takes `_facts[0]..[6]`. Insert a field in the middle and nothing errors: Tilt simply guards on the wrong context or binds the wrong port. The field count and order are the contract, so they are pinned here rather than left to whoever edits `ports.sh` next.
## the caller's env beats the files
`lib/config.sh` states one precedence rule: `versions.env` < `env.d/<profile>` < `ctrl/.env` < the caller's env. It is enforced by `CONFIG_OVERRIDABLE`, a hand-maintained list, and a key missing from it loses to the file SILENTLY. `REGISTRY_PORT` and `MANIFESTS_DIR` were both missing on 2026-09-13 and were found by accident.
So the loop is generated FROM the list: add a key to `CONFIG_OVERRIDABLE` and the test starts asking about it without anyone remembering to come here. Three keys name something that must exist and are validated at load, so they get a real alternative rather than a sentinel.
## one derivation, not three
The Makefile used to compute the cluster name itself and sed `TILT_PORT` out of `ctrl/.env`: a second derivation of values `lib/config.sh` already owns, which could disagree with it after `ports.sh persist`. It now reads `ports.sh active`. Nothing structurally prevents the sed coming back, so the agreement is asserted against the real `make -n` output rather than against the source.
`--no-print-directory` and a grep, not `tail -1`: run from `make selftest` this is a RECURSIVE make, and the "Entering/Leaving directory" lines go to STDOUT. `tail -1` then reads "make[1]: Leaving directory ..." and both checks fail, but only when invoked through make, never when the script is run directly. A test that passes one way and fails the other is worse than no test.
## identity follows the folder, safely
The cluster name is NOT the bare directory name: kind needs a DNS label, so `default_cluster_name` lowercases it and replaces everything outside `[a-z0-9-]`. Re-deriving that anywhere else is how a copy ends up guarding the wrong context, which is exactly why the Tiltfile asks instead of computing.
## ports are stable across versions
Not a change-detector. The block is derived, never stored, so if the derivation shifts then every EXISTING environment's ports move underneath it: a running cluster keeps its old ports while rig starts reporting new ones, and `ports.sh show` stops describing reality. Anchored to three known names.
## rig stays standalone
rig sits inside a host project's tree but must be copyable straight out of it: no imports, no paths, no assumption the host is there. This grep is the whole test of that claim, and until it was added it lived only in prose and in whoever remembered to run it.
The pattern is assembled from fragments so the file does not match ITSELF. Writing it literally would fail forever; excluding the file instead would put a blind spot in the one check that guards the boundary.
## the Tiltfile hardcodes nothing
Every other Tiltfile on this machine writes its slug in five or six times by hand, so a copied project deploys into the original's cluster until someone edits all of them. rig's asks `ports.sh`. A literal `kind-<name>` in it would mean that has been undone.
## standalone kits are generated and current
The kits under `standalone/<profile>/` are rig flattened into single files, one per profile. A kit left behind by a change to rig is exactly the drift they replaced (`rigmini.sh` once said 2 GB per node long after rig measured 800 MB), so a stale kit fails here rather than waiting to be noticed on another machine.
## kit Makefiles call only real verbs
Each kit's Makefile exists so nothing wrapping these scripts has to GUESS how to call them. A generated Makefile once did guess: `rigmini.sh on`, not a verb, and a bare `rigdeps.sh` for "check and report", which installs. So every target's default verb must be one its script's own dispatch accepts, read from that dispatch, not from a list that could drift from it.
## export carries choices, not credentials
An export is "take the setup I have here somewhere else", so it carries this machine's CHOICES (profile, ports, manifest dir) and never its credentials: `ctrl/.env` can hold registry and mirror logins next to those choices. The committed per-profile kits carry neither, since they must be the same on any machine. Proven with sentinel values in a scratch copy, because the real `ctrl/.env` may have those keys empty, and an empty value proves nothing.
## optional: Tiltfile evaluates
Parsing the Tiltfile for real is the only way to know it still evaluates, but Tilt snapshots a kubectl context before parsing, so it cannot run without a cluster. Skipped rather than failed when there is none, the same way docgen skips its graphgen section.

31
rig/docs/notes/standalone.md Normal file
View File

@@ -0,0 +1,31 @@
# ctrl/standalone.sh
## Purpose
Generates the standalone kits: single-file versions of rig's own tools, one folder per profile, for machines the full rig is not going to.
A kit is a pure function of rig as it is right now. It gains nothing rig lacks and loses nothing rig has: improve rig, regenerate, and every kit follows. Nothing in `standalone/<profile>/` is ever edited by hand.
## The contract
What this file does NOT know, on purpose: which tools rig has, what they are called, how its libraries are split, where configuration lives or what it contains. Rig will change shape (scripts get split, renamed and grow new libraries), and a generator that encoded today's layout would quietly produce a wrong kit the first time it did. So it works from a contract a script opts into, and from nothing else:
1. A marker comment, alone on a line near the top, declares an entry point: `(hash) rig:standalone <kit-name> <default-verb>`. The default verb must only REPORT: it is run as a smoke test.
2. Every `source` an entry point makes names a `.sh` file by a path that resolves relative to the entry point. Libraries may source further libraries however they like; bash follows those itself.
3. Configuration enters through `load_config`, and the libraries provide `config_profiles`, `config_freeze <profile|--current>` (which prints a replacement `load_config` with that resolution frozen in) and, for an export, `config_current_profile` and `config_left_out`. How config is layered, stored, derived or frozen is rig's business; the generator only asks, and embeds the answer without interpreting it.
## Bash does the resolving
Bash does the resolving, not a parser in the generator. Libraries are sourced in a clean shell and read back with `declare -f` and `declare -p`, so any structure bash can load, this can flatten.
## Every kit is proven before it is written
Every kit is PROVEN to stand alone before it is written: no `source` left, no path into rig's tree in its code, `bash -n` clean, and its default verb run in an empty directory with nothing from rig present. A shape the generator has never seen either passes that, or generation stops and names the kit, the file, the line and what is wrong. It never writes a kit that only looks finished.
## Usage: write, check, export
- `standalone.sh write`: generate every kit into `standalone/<profile>/`.
- `standalone.sh check`: generate into a scratch dir and fail if any kit differs.
- `standalone.sh export DIR`: ONE kit for the configuration this machine runs (its profile plus the choices in its local config, WITHOUT its credentials), written outside the repo.
`write` and `check` are what gets committed: one kit per profile, identical on any machine. `export` answers the other question, "take the setup I have here somewhere else", so it reflects this machine, and for exactly that reason it never lands in the repository.

41
rig/docs/notes/versions.md Normal file
View File

@@ -0,0 +1,41 @@
# ctrl/versions.env
## Pinned toolchain
The single manifest `ctrl/deps.sh` installs from. Every entry is a single binary; none of them needs an apt repo.
- kubectl — fully static
- kind — libc only
- tilt — libc + libstdc++ + libgcc (present in base Debian)
- jq — upstream static build (Debian's is linked against libjq/libonig)
Checksums are the upstream-published SHA256 of the linux/amd64 artifact.
## Bumping a pin
Change the version, then take the checksum from the release's own published list — never hand-edit or hand-copy one from a download you did. For anything hosted on GitHub releases that is:
```
curl -sSL https://github.com/<org>/<repo>/releases/download/<tag>/checksums.txt \
| grep linux.x86_64
```
(kubectl publishes its own instead: `<KUBECTL_URL>.sha256`.)
There was a `ctrl/versions-refresh.sh` named here that has never existed. If bumping stops being rare enough to do by hand, write it — but a comment pointing at a missing script is worse than no comment.
## ctlptl
Creates a kind cluster WITH a local registry wired in, which is what keeps images off docker.io (an unqualified name means `docker.io/library/<name>`). Same publisher and same archive shape as tilt: binary at the archive root, so `fetch_tgz` handles it with strip=0 and no special case.
## docker compose
The distro docker packages ship the daemon and the CLI but frequently not this, so `docker compose up` fails with "unknown command" on an otherwise working Docker. It is a CLI plugin, found by NAME in a plugin directory, so a copy in the bin dir alone only gives you the retired `docker-compose` v1 spelling; deps.sh links it into `~/.docker/cli-plugins`.
## Node images
Node images shipped with `KIND_VERSION`, pinned by digest so a kind upgrade can never silently move the k8s version. Profiles select one via `K8S_VERSION`. Older entries are kept deliberately: running a trailing-edge control plane is part of simulating a legacy estate.
## Cabinets
Public services dropped in as-is, the upstream image unmodified. The same declaration installs on compose or in the cluster, so a dependency is named once and works either way. Pinned by tag rather than digest because they are ordinary upstream images with no supply chain claim attached — bump freely, and preload them for the offline profile.