Skip to main content
A world image is your product’s own image with a few things added: Postgres (and any other datastore the product uses), 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 in database.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’s fixtures/acme-crm/Dockerfile.miroir:
To adapt it to another product, keep four things:
  1. RUN miroir bake is the last RUN. Declare the build arguments the seed needs (such as ARG WORLD) right before it, so every layer above is shared between worlds.
  2. The image ends as root, with tini as PID 1 in place of the product’s entrypoint. That way docker run IMAGE cat /path works, and zombie processes are reaped.
  3. /bin/sh stays in the image. Harbor runs the collect hook through sh -c.
  4. database.url connects 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’s crm_app role shows.
Locally the Miroir image is 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:
From top to bottom:
  • expose lists the ports the agent may reach: the CRM’s API, on 3000. Only these ports may listen off loopback, so the datastores bind to 127.0.0.1 and the web server to 0.0.0.0.
  • processes start in order, datastores first. Each server has a ready probe that must pass before the next process starts. Workers have none.
  • env applies 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.
  • bake commands run at build with only the datastores up: create the database, migrate, seed, and create the product’s own role.
  • seed commands run at build with every process up, to build data through the product’s own API.
  • database names the graded database and the column left out of capture. time names a column whose dates never move, and an integer column that holds Unix time.
  • sinks are the recorders for outgoing mail and HTTP. responses gives the payment API a canned answer.
  • quiet passes once the email queues are empty, so Miroir knows background work is done.
The manifest reference lists every key and its rules, and explains how dates, sinks and quiet work.

Build and boot

The bake runs inside docker 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:
A failed boot stops the container. Either way, the message names the step that failed and how to fix it. World lifecycle lists every step and every failure message.

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.
Read a file from the image, collect from a running world as Harbor does, and read the evidence:
Open a shell in 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:
  1. Scrub the dump before it leaves the customer’s network. Miroir does not scrub.
  2. Restore it in a bake command (pg_restore), and set database.time.captured to 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.
  3. Build one image per snapshot. Put the COPY of the dump and RUN miroir bake last in the Dockerfile, so the product and datastore layers are shared and each snapshot adds one layer.
  4. Keep a private snapshot in a private image. See where images must be public.
  5. 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 become solution/solve.sh, using curl -fsS. Then draft the spec from reference runs.