# rig

rig builds a disposable Kubernetes environment on your machine, so you can see how a system
fits together without access to any of it. It is for **onboarding and exploration**, not a
production replica.

Most services in it are **not real**. What has to be faithful is the topology: names, ports,
dependency order, who can reach whom, and how it fails. That is what makes a whole estate fit on
a laptop. A real 20-service platform does not fit once in 14 GB; stubs of about 30 MB each fit
three times.

Under the hood it is a kind cluster, a local image registry and a Tilt dev loop, each with its
own name and ports, so several environments run side by side. What runs on it is an
**overlay**: a folder outside rig that holds one use case.

## Using rig from a project

You don't need to read rig to use it. Get a release (`rig-<version>.tar.gz`, or a checkout at
the tag `rig-<version>`), extract it anywhere, and point the project at it (`RIG_DIR`). Then run
`make check`: it says what the machine still lacks and which command comes next. `.version`
names the release; a project records the one it was last run against. See
[`docs/notes/overlay.md`](docs/notes/overlay.md).

## Prerequisite

**Docker.** Nothing else: no curl, jq, python or apt repositories.

On Windows, rig runs inside WSL. Run `wsl --install` once, from an elevated shell, then reboot.
Work inside the Linux filesystem, not `/mnt/c`: file watching doesn't work there, and
`make deps` warns about it. Git Bash, MSYS and Cygwin don't work (no `/proc`, no docker socket).

| symptom | cause |
| --- | --- |
| "the virtual machine could not be started" | virtualization disabled in BIOS/UEFI |
| the command is not recognised | Windows build too old (needs 2004 or later) |
| the install starts, then nothing works | a reboot is still pending |

On a machine with nothing but Docker, [BOOTSTRAP.md](BOOTSTRAP.md) runs the toolchain through
the installer container.

## What it does

| command | does |
| --- | --- |
| `make docs` | serves the docs locally; works before anything is installed |
| `make check` | is this machine ready? memory, toolchain, cluster, the next command (`check all` for every detail) |
| `make deps` | installs the pinned toolchain (`deps core` on a managed machine) |
| `make cluster up` | the cluster, its registry and the configured addons (`down`, `reset`, `list`, `free`) |
| `make tilt` | the dev loop: rig's part, then the overlay's Tiltfile |
| `make selftest` | checks rig itself |
| `make help` | every target |

Every verb is a `Makefile` target calling one script in `ctrl/`. The aliases (`kind-up`,
`tilt-up`, …) call the same scripts.

## Overlays

An overlay holds its settings (`rig.env`), its manifests (`k8s/overlays/dev`), its Tiltfile and
images, its addons, and its kind config if it needs one. rig reads it and never writes into it.

```bash
cp -r examples/starter local/myenv        # local/ is ignored
OVERLAY=local/myenv make cluster up
OVERLAY=local/myenv make tilt
```

With no overlay named, rig runs `examples/starter`. [`examples/data`](examples/data/) adds
postgres, redis and airflow as plain manifests. A project can carry rig at `./rig`, or keep it
anywhere and name it with `RIG_DIR`.

The cluster name, context, image tags and ports derive from the overlay folder's name (rig's
own, with no overlay), so environments never collide, and one's teardown never touches another.

## Configuration

Layers, weakest first: built-in defaults < `ctrl/versions.env` < the profile < the overlay's
`rig.env` < `ctrl/.env` < the command line. A profile (`ctrl/env.d/`) is optional and says how
this machine reaches the world: `mirror` (a pull-through cache) and `offline` (air-gapped) ship
as examples. The cluster itself is one kind template: the overlay's, or rig's one-node default.

rig's own addons make the cluster work: `metallb` (LoadBalancer addresses), `cert-manager` (a
local CA), `metrics-server` (`kubectl top`). A workload's database, cache or scheduler belongs to
its overlay. There is no ingress controller: services are reached through LoadBalancer
addresses, or through the overlay's own gateway on the environment's HTTP port.

## Where things are

```
Makefile          the verbs
.version          this release: patch and minor steps are edits here; milestones get a tag
ctrl/             one script per verb; lib/config.sh (settings and layers); Tiltfile (rig's
                  half of the dev loop); k8s/kind-config.yaml.tpl; addons/; env.d/; versions.env
docs/             index.html (make docs); notes/, one per script: why the code is as it is
examples/         starter (the default overlay), data (postgres, redis, airflow)
standalone/       single-file kits generated from ctrl/ (make standalone); never edited by hand
tests/            the installer's host fixtures
BOOTSTRAP.md      from a bare machine with only Docker
STALE.md          assumptions withdrawn, each checked by selftest
```