tini, the miroir binary, and a manifest at /miroir/miroir.yaml.
Its data, the world, is seeded once at docker build, and every trial boots a fresh copy of it.
Harbor runs the world image as a compose service next to the agent’s container, main. The agent
reaches it only on the ports the manifest exposes.
Two working worlds to copy from:
fixtures/acme-crm, a small CRM with Postgres, Redis, a web server, a worker, an email queue and a payment API. This page uses it as the example.examples/gitea, stock Gitea wrapped with configuration only, one image per world.
Map the product
Start by listing every long-running process (web servers, workers, schedulers) and every datastore, with its command, port, user and environment. The product’s compose file usually holds most of this. Then find out:- Where its data comes from: migrations, seed scripts, or a scrubbed dump.
- How its API authenticates, so the world can seed a test account and a credential for it.
- What it sends out: email, webhooks, payment or other HTTP calls, and the base URLs that will point them at Miroir’s recorders.
- What runs in the background: queues, cron, schedulers, and how to tell when they are done.
- Which columns change on every request, such as a token’s
last_used_at. Those go indatabase.ignore; otherwise every request that touches them shows up as a change.
Write the Dockerfile
The world’s Dockerfile starts from the product’s image and adds the rest. The fixture’sfixtures/acme-crm/Dockerfile.miroir:
RUN miroir bakeis the lastRUN. Declare the build arguments the seed needs (such asARG WORLD) right before it, so every layer above is shared between worlds.- The image ends as
root, withtinias PID 1 in place of the product’s entrypoint. That waydocker run IMAGE cat /pathworks, and zombie processes are reaped. /bin/shstays in the image. Harbor runs the collect hook throughsh -c.database.urlconnects as a Postgres superuser, because change capture installs triggers and the date shift disables them while it runs. The product’s own roles must not be superusers: give them only the privileges they need, as the fixture’scrm_approle shows.
miroir:dev, which docker buildx bake builds in the Miroir
repository. Releases publish ghcr.io/raphaeldkhn/miroir:<major>.<minor>.
Write the manifest
The manifest,/miroir/miroir.yaml, tells Miroir how to run the product: which processes to
start, how to seed the world, which database to grade, and where outgoing mail and HTTP calls go.
The fixture’s
miroir.yaml
uses every key but database.time.captured:
exposelists the ports the agent may reach: the CRM’s API, on 3000. Only these ports may listen off loopback, so the datastores bind to127.0.0.1and the web server to0.0.0.0.processesstart in order, datastores first. Each server has areadyprobe that must pass before the next process starts. Workers have none.envapplies to every process and command. It points the product at the datastores, at the SMTP recorder on port 2525 and at the HTTP recorder on 9000. It also turns the scheduler off, so nothing changes while the world sits idle.bakecommands run at build with only the datastores up: create the database, migrate, seed, and create the product’s own role.seedcommands run at build with every process up, to build data through the product’s own API.databasenames the graded database and the column left out of capture.timenames a column whose dates never move, and an integer column that holds Unix time.sinksare the recorders for outgoing mail and HTTP.responsesgives the payment API a canned answer.quietpasses once the email queues are empty, so Miroir knows background work is done.
Build and boot
The bake runs insidedocker build, so building the image seeds the world, and a failed bake
fails the build. In the Miroir repository, docker buildx bake builds the fixture’s world,
acme-crm-env:dev.
Then boot the image in the foreground. The log shows each process’s output, then the boot’s timing
line, booted in …. Ctrl-C stops it:
Debug a world
Try a manifest change without rebuilding, by mounting it over the baked one. This works for everything that acts at boot (processes,env, expose, sinks, quiet, dates). Changes to
bake and seed need a rebuild.
main with the world running, to see what an agent sees (Harbor’s
harbor task start-env):
From production
A production snapshot becomes a world with no import or scrub code in Miroir:- Scrub the dump before it leaves the customer’s network. Miroir does not scrub.
- Restore it in a
bakecommand (pg_restore), and setdatabase.time.capturedto the time the dump was taken. The bake moves every time column from then to the bake’s start, so relative ages hold however late the image is built. Each boot then moves the world to the trial’s day, as for any world. - Build one image per snapshot. Put the
COPYof the dump andRUN miroir bakelast in the Dockerfile, so the product and datastore layers are shared and each snapshot adds one layer. - Keep a private snapshot in a private image. See where images must be public.
- Turn tickets into tasks. The ticket becomes
instruction.md: the request in the requester’s words, and the account the agent acts as. The API calls that resolved it becomesolution/solve.sh, usingcurl -fsS. Then draft the spec from reference runs.