Running WireMock in Docker Compose: Exact Configuration & Troubleshooting

When orchestrating local development environments, Tool-Specific Implementation & Setup requires precise container orchestration to prevent port collisions and state loss. Deploying WireMock via Docker Compose delivers a deterministic, isolated mock server aligned with modern microservice architectures. This guide provides exact configurations, CLI commands, and targeted resolutions for deployment failures.

1. Core `docker-compose.yml` Configuration

Initialize a minimal, production-aligned service definition. Pin the image tag in production to prevent CLI flag deprecation. Use restart: unless-stopped to maintain mock availability during host reboots without triggering unnecessary container churn.

version: '3.8'
services:
 wiremock:
 image: wiremock/wiremock:3.5.4
 container_name: wiremock
 restart: unless-stopped
 ports:
 - "8080:8080"
 - "8443:8443"
 command:
 - "--root-dir=/home/wiremock"
 - "--global-response-templating"
 - "--enable-stub-cors"
 - "--max-request-journal-size=1000"
 volumes:
 - ./wiremock/mappings:/home/wiremock/mappings
 - ./wiremock/__files:/home/wiremock/__files
 - ./wiremock/logs:/home/wiremock/logs
 healthcheck:
 test: ["CMD", "curl", "-f", "http://localhost:8080/__admin/health"]
 interval: 10s
 timeout: 5s
 retries: 3

Action: Run mkdir -p wiremock/{mappings,__files,logs} before starting the stack to prevent Docker from creating root-owned directories.

2. Volume Mapping & Stub Persistence

Stateless mock containers wipe stub definitions and request journals on restart. Persist state across sessions by bind-mounting the mappings and __files directories. When architecting Dockerized Mock Environments, always align the host mount path with the --root-dir=/home/wiremock CLI flag. Mismatched paths trigger immediate 404 responses for all stubbed endpoints.

Prevention: Validate all mappings/*.json files against the WireMock v3 schema before deployment. Use jq . wiremock/mappings/*.json to catch malformed JSON early.

3. Network Routing & CORS Configuration

Frontend applications running on localhost:3000 or localhost:5173 trigger preflight failures if the mock server does not explicitly handle cross-origin requests. The --enable-stub-cors and --global-response-templating flags resolve this natively.

For platform teams integrating into shared CI/CD agents, avoid binding collisions by exposing the port dynamically:

ports:
 - "0.0.0.0:${WIREMOCK_PORT:-8080}:8080"

Use the extra_hosts directive if your frontend resolves API calls via a custom domain alias (e.g., api.local).

4. Targeted Fixes for Common Failure Modes

Symptom	Root Cause	Exact Resolution
`CrashLoopBackOff` / `AccessDeniedException`	UID/GID mismatch between host and container user	Add `user: "${UID:-1000}:${GID:-1000}"` to the service definition
YAML parse errors on startup	Incorrect `command` array indentation or syntax	Use explicit list syntax (`- "--flag=value"`) instead of multiline strings
Heap exhaustion during QA runs	Unbounded request journal growth	Enforce `--max-request-journal-size=1000` in the `command` array
Healthcheck fails immediately	Missing `curl` binary or wrong port binding	Verify `8080/tcp` is exposed; switch to `wget` if using a `slim` base image

5. Integration with Frontend & QA Workflows

Deployment & Verification:

docker compose up -d wiremock
docker compose exec wiremock curl -f http://localhost:8080/__admin/health

QA Validation: Query /__admin/requests to inspect exact payload structures, header propagation, and unmatched request logs before executing automated test suites.

Frontend Proxy Configuration: Route /api/* traffic to http://localhost:8080 via your framework’s dev server:

Vite: server.proxy = { '/api': 'http://localhost:8080' }
Next.js: rewrites: [{ source: '/api/:path*', destination: 'http://localhost:8080/api/:path*' }]
Webpack: devServer.proxy = { '/api': { target: 'http://localhost:8080', secure: false } }

This proxy pattern eliminates hardcoded mock URLs, enforces environment parity across staging and production, and allows seamless switching between real and mocked backends.