Run the image

Updated Sep 29, 2026·4 min read

The image runs anywhere an image runs: a laptop, a CI job, one server or Kubernetes. The backend's Quick start tab has the commands for each, with your registry, image name and version filled in.

The Quick start page: Try it, One server, With a database and Kubernetes, and the commands to sign in, start the image and check it answers. — Quick start: four ways to run the image, and the commands for each.

On this page, <image> stands for your image and its version, such as <your-org>.registry.mockzilla.org/ci-payments:v2026.09.23.3.

Pick a way to run it

Try it: on a laptop or a CI job. Everything stays in memory, so a restart starts from nothing.
One server: keeps its state across restarts, in one SQLite file on a volume.
With a database: a compose file with PostgreSQL, so several copies share one database.
Kubernetes: a Deployment that pulls with a secret and reads its storage settings from another.

Each one needs a registry credential.

See Pull your image.

Try it

docker login <your-org>.registry.mockzilla.org
docker run --rm -p 2200:2200 <image>

Then check it answers:

curl http://localhost:2200/healthz

The API explorer is at http://localhost:2200, unless you turned it off.

Good to know

It listens on port 2200. Set APP_BASE_URL to the address your clients use, or links in its responses stay relative.
It runs as user 65532. A volume it writes to has to belong to that user. Keep the volume on a local disk: a folder shared from macOS or Windows, or NFS, loses writes.
It refuses to start when it cannot reach its storage. It never falls back to memory.
docker run --rm <image> about lists what the image carries: its build details, its services, its SBOMs and its security report.

Change a setting when you run it

The image starts with the values from the backend's Runtime defaults. Each one is an environment variable, and a value you pass when you run the image wins over the one inside it:

APP_DISABLE_UI: true hides the API explorer.
ROUTER_HISTORY_ENABLED: false stops recording requests and responses.
ROUTER_REPLAY_ENABLED: true turns replay on.

For example:

docker run -e ROUTER_HISTORY_ENABLED=false <image>

Storage has variables of its own.

See Storage drivers.

Your own files, with no new build

The image carries the contexts, scenarios and service config you set in the workspace. To change them without building again, mount a folder at /etc/mockzilla/config, or point MZ_CONFIG_DIR at one. It holds one folder per service:

services/<route key>/setup/context.yml
services/<route key>/setup/scenarios.yml
services/<route key>/setup/config.yml

A file you mount replaces the image's file of the same name. A file you leave out keeps the image's.

To start from what the image carries, take data.mockz from the files that ship with the image. It is a .tar.gz of the same folders, and tar -xzf data.mockz unpacks it.

The license at run time

The image reads its license when it starts and checks it every hour. What it needs depends on how it gets its license:

Carried inside: nothing to set. To give it a newer license, mount the file at /etc/mockzilla/license.json.
Fetched from us: a route to your registry's hostname. Keep a volume at /var/lib/mockzilla, so a new container starts with the license it already fetched.

Once its license expires, a running image answers every request with an error, and a new one does not start.

See Licenses.