# `examples/starter` — the overlay rig runs when you name none

An overlay is one folder, outside rig, that holds what runs: its settings, its
manifests, its images. rig reads it and never writes into it — see
[`docs/notes/overlay.md`](../../docs/notes/overlay.md) for the contract. This one
ships with rig so `make tilt` has something to deploy on a fresh clone, and so a
real overlay has a shape to be written against:

```
rig.env              settings layered over rig's defaults (this one sets none)
k8s/base/            the components, as plain manifests
k8s/overlays/dev/    how this environment differs from the base — MANIFESTS_DIR's default
Tiltfile             the workload's half of the dev loop; rig's ctrl/Tiltfile includes it
Dockerfile.example   the shape of an image you build yourself
```

To start your own, copy this folder somewhere rig does not track —
`rig/local/<name>/`, or a repo of its own — and name it:

```bash
cp -r examples/starter local/myenv
OVERLAY=local/myenv make cluster up      # or OVERLAY=local/myenv in ctrl/.env
```

The cluster, context and port block then follow the overlay's folder name
(`myenv`, `kind-myenv`), so it never collides with another.

## The two components are examples, not the system

They exist so the real manifests have a shape to be written against.

### The three states a component can be in

Switching between them should be a one-line change, never a rewrite. The DNS
name stays the same in every case, so callers never know the difference:

| state | what exists | when |
| --- | --- | --- |
| **real** | an image built from source, hot-reloaded | the one thing you are working on |
| **mock** | a stub returning canned responses (`example-mock.yaml`) | everything else — most of the estate |
| **remote** | no pod at all, just a Service (`example-remote.yaml`) | when the real system is reachable and you want it |

Most components should be **mock**. What has to be faithful is the topology —
names, ports, dependency order, who can reach whom, how it fails. The workloads
are noise, and mocking them is what makes several copies of a large estate fit
on one laptop.

## Images

`Dockerfile.example` is a commented shape, not a working build. Paths in this
folder's Tiltfile are relative to this folder, so `context='.'` is the overlay
and every `COPY` in the Dockerfile is relative to it:

```
docker_build(CLUSTER + '-api', context='.', dockerfile='Dockerfile.api')
```

The name given to `docker_build` must match `image:` in the manifest — that
string is the only thing connecting the two.