Skip to content
Docs | Mimic

Docker

The fastest way to run Mimic is a single docker run command. The image is around 90 MB compressed and supports both linux/amd64 and linux/arm64.

Minimal run command

Section titled “Minimal run command”
Terminal window
docker run -d \
  --name mimic \
  -p 8080:8080 \
  -v $(pwd)/mocks:/app/mocks:ro \
  ragilhadi/mimic:latest

Breakdown:

  • -d runs the container in the background.
  • --name mimic gives the container a stable name so you can docker stop mimic later.
  • -p 8080:8080 maps host port 8080 to container port 8080.
  • -v $(pwd)/mocks:/app/mocks:ro mounts your local ./mocks folder into the container as read-only.
  • ragilhadi/mimic:latest is the image. Pin to a specific tag in production.

Mounting on Windows

Section titled “Mounting on Windows”

If you’re on Windows, $(pwd) won’t work in cmd or PowerShell. Use the full path or PowerShell’s ${PWD}:

Terminal window
docker run -d `
  --name mimic `
  -p 8080:8080 `
  -v ${PWD}/mocks:/app/mocks:ro `
  ragilhadi/mimic:latest

Running on a different port

Section titled “Running on a different port”
Terminal window
docker run -d \
  --name mimic \
  -p 9000:9000 \
  -e PORT=9000 \
  -v $(pwd)/mocks:/app/mocks:ro \
  ragilhadi/mimic:latest

Both the host port mapping and Mimic’s internal port need to change. See Environment Variables.

Restricting network access

Section titled “Restricting network access”

Mimic binds 0.0.0.0 (every interface) by default. Inside a container that’s fine — leave it alone, and restrict access at the host level instead by only publishing the port to localhost:

Terminal window
docker run -d \
  --name mimic \
  -p 127.0.0.1:8080:8080 \
  -v $(pwd)/mocks:/app/mocks:ro \
  ragilhadi/mimic:latest

-p 127.0.0.1:8080:8080 (instead of -p 8080:8080) means the published port only accepts connections from the Docker host itself — nothing on the network can reach it. Setting MIMIC_BIND_ADDRESS=127.0.0.1 inside the container has no equivalent effect on a published port, since the container’s own loopback isn’t the host’s. See Binding Address and What the Request Log Keeps for why this matters — the admin API has no authentication unless you set MIMIC_ADMIN_TOKEN.

Health checks

Section titled “Health checks”

Mimic exposes a /health endpoint. Use it for Docker’s built-in health check:

Terminal window
docker run -d \
  --name mimic \
  -p 8080:8080 \
  -v $(pwd)/mocks:/app/mocks:ro \
  --health-cmd="bash -c 'exec 3<>/dev/tcp/127.0.0.1/8080 && printf \"GET /health HTTP/1.0\\r\\n\\r\\n\" >&3 && head -1 <&3 | grep -q \" 200 \" || exit 1'" \
  --health-interval=10s \
  --health-timeout=3s \
  --health-retries=3 \
  ragilhadi/mimic:latest

The image is based on Debian Trixie Slim with only the base package set plus the TLS trust bundle, so wget and curl are not installed. bash is, which is why the probe uses its built-in /dev/tcp instead. If you change PORT, change it in the probe too.

Managing the container

Section titled “Managing the container”
Terminal window
# View logs
docker logs -f mimic


# Restart
docker restart mimic


# Stop and remove
docker stop mimic && docker rm mimic


# Pull a newer version
docker pull ragilhadi/mimic:latest
docker stop mimic && docker rm mimic
# (then run again with the same command)

Pinning to a version

Section titled “Pinning to a version”
Terminal window
docker pull ragilhadi/mimic:v1.0.0
docker run -d --name mimic ragilhadi/mimic:v1.0.0

Browse available tags on the Docker Hub page.

Where to next

Section titled “Where to next”