Running Mocko

Docker Images

Mocko ships three images: an all-in-one standalone image, and a split pair with the mock server and the control panel as separate containers. This page explains what each contains and how to choose.

The three images

ghcr.io/mocko-app/standalone wraps the CLI: mock server, control panel, and file watching in one container. Ports 8080 (mocks) and 6625 (UI), mocks mounted at /var/mocks.
ghcr.io/mocko-app/core is just the mock server, the component that receives your traffic. Port 8080.
ghcr.io/mocko-app/control is just the control panel. Port 6625. It talks to core through a shared secret and stores its state in Redis.

When each fits

Standalone is the right default for local work and simple single-container setups: nothing to wire, watch mode on, UI included. It is what the Docker Compose page uses.

Core and control split is for shared deployments. The two components have different lives: core sits on the hot path of your test traffic and may need several replicas, while control serves a handful of developers and one replica is plenty. Splitting them lets you scale, restart, and secure each independently, and drop control entirely where nobody needs a UI.

Deploying the split images to Kubernetes by hand means recreating the wiring below as manifests. The Helm chart does exactly that, including the shared secret, probes, and an optional Redis, so prefer it on Kubernetes.

Running the split pair

Core and control connect through two things: a Redis both can reach, and a shared deploy secret that lets control push changes to core. The essential wiring, shown as plain docker run commands:

$docker run -d --name mocko-core -p 8080:8080 -e REDIS_ENABLED=true -e REDIS_URL=redis://redis:6379 -e DEPLOY_ENDPOINT_ENABLED=true -e DEPLOY_SECRET=change-me ghcr.io/mocko-app/core:2

$docker run -d --name mocko-control -p 6625:6625 -e MOCKO_CORE_URL=http://mocko-core:8080 -e MOCKO_DEPLOY_SECRET=change-me -e REDIS_ENABLED=true -e REDIS_URL=redis://redis:6379 ghcr.io/mocko-app/control:2

DEPLOY_SECRET on core and MOCKO_DEPLOY_SECRETon control must match; it authenticates control's internal calls to core.
DEPLOY_ENDPOINT_ENABLED=true opens the internal endpoint control uses to apply changes. Leave it unset on a core that runs without control.
Both point at the same Redis. The split setup effectively requires Redis: it is where deployed mocks, hosts, and flags live, and how multiple core replicas stay consistent.

Core reads the same environment variables in any setup, so proxying (PROXY_BASE-URI), timeouts, and auth are configured identically here and in the standalone image.

File mocks in images

Core loads .hcl files from /var/mocks. You can mount them, but for shared environments baking them in wins: the image becomes a versioned, rollback-able artifact of your team's mock behavior.

FROM ghcr.io/mocko-app/core:2
COPY mocks/ /var/mocks/

Behavior details

Health checks: core answers on GET /__mocko__/health, control on GET /api/health. Point container or orchestrator probes there.
On shared instances, consider MANAGEMENT_AUTH_MODE to require a bearer token on management routes; see the configuration reference.
The 2 tag on all three images always points at the latest Mocko v2 release, with no breaking changes within v2. Use the same tag across core and control.