Running Mocko

Docker Compose

If your local stack already lives in a compose file, Mocko slots in as one more service. This page sets up the standalone image with mounted mock files, adds Redis persistence, and points your app at it.

A minimal setup

services:
  mocko:
    image: ghcr.io/mocko-app/standalone:2
    ports:
      - "8080:8080"   # mock server
      - "6625:6625"   # control panel
    volumes:
      - ./mocks:/var/mocks

$docker compose up mocko

The image runs the CLI in watch mode against /var/mocks, so anything you learned in File Mocks applies as-is: edit a file in ./mocks on your machine and the container reloads it.

Proxying to a backend service

The image exposes the proxy settings as environment variables. MOCKO_URLis the proxy target for unmatched requests (the CLI's -u), and MOCKO_TIMEOUT is the proxy timeout in milliseconds (-t, default 30000). Compose service names resolve inside the network, so the target is usually another service:

services:
  api:
    build: ./api

  mocko:
    image: ghcr.io/mocko-app/standalone:2
    ports:
      - "8080:8080"
      - "6625:6625"
    environment:
      MOCKO_URL: http://api:3000
    volumes:
      - ./mocks:/var/mocks

Point your frontend at http://localhost:8080 instead of the API and you get the selective-mocking setup from Mock One Edge Case for the whole team, with the mocks folder committed next to the compose file.

Adding Redis persistence

Add a Redis service and the REDIS_* variables, and UI-created mocks, hosts, and flags survive docker compose down:

services:
  redis:
    image: redis:6-alpine
    volumes:
      - ./data/redis:/data

  mocko:
    image: ghcr.io/mocko-app/standalone:2
    ports:
      - "8080:8080"
      - "6625:6625"
    environment:
      REDIS_ENABLED: "true"
      REDIS_URL: redis://redis:6379
    volumes:
      - ./mocks:/var/mocks
    depends_on:
      - redis

When and why to do this is covered on Persistence and Redis; the short version is that storeless is great until you want shared or durable state.

Standing in for several services

To use host-based routing in compose, give the Mocko container the hostnames your app already calls, using network aliases:

services:
  mocko:
    image: ghcr.io/mocko-app/standalone:2
    networks:
      default:
        aliases:
          - billing.local
          - catalog.local
    volumes:
      - ./mocks:/var/mocks

Your app resolves billing.local to the Mocko container, the Host header arrives as billing.local, and the host blocks in your mock files take it from there.

Behavior details

The 2 tag always points at the latest Mocko v2 release, and v2 releases never break compatibility, so it is safe to stay on it.
The container runs as a non-root user (uid 10001). If the mounted mocks folder is not readable by that user, the container logs load errors instead of serving your files.
All core environment variables pass through to the standalone image, so anything configurable on a deployed core can be set here too.