$docker.recipes

WireMock

intermediate

API mocking and service virtualization.

[i]Overview

WireMock is a powerful API mocking and service virtualization tool originally developed for Java applications but now available as a standalone service. It enables developers and testers to create realistic HTTP service stubs that can simulate real APIs with complex behaviors, including response delays, fault conditions, and stateful interactions. WireMock has become essential in modern software development for testing microservices, enabling parallel development, and creating predictable test environments. This Docker configuration deploys WireMock as a containerized service with persistent volume mappings for stub definitions and static response files. The setup maps local directories for both JSON mapping files that define API endpoints and response behaviors, plus a files directory for serving static content. The verbose logging mode provides detailed request/response information for debugging mock behaviors during development. Development teams building microservices architectures, QA engineers creating comprehensive test suites, and DevOps professionals setting up CI/CD pipelines will find this configuration particularly valuable. The containerized WireMock instance allows teams to maintain consistent API mocks across different environments while enabling rapid iteration on service contracts without dependency on actual backend services.

[*]Key Features

  • [+]HTTP request matching with URL patterns, headers, query parameters, and request body content
  • [+]Response templating with dynamic content generation using Handlebars syntax
  • [+]Request recording and playback functionality to capture real API interactions
  • [+]Stateful behavior simulation with scenarios for multi-step API workflows
  • [+]Fault injection capabilities including random delays, connection resets, and HTTP error responses
  • [+]Admin REST API for runtime stub creation and management without file system access
  • [+]JSON-based stub definitions with support for complex request matching rules
  • [+]Static file serving for binary content, images, and documents through __files directory

[#]Common Use Cases

  • [1]Frontend development teams mocking backend APIs that are still under development
  • [2]Integration testing of microservices without dependencies on external third-party APIs
  • [3]Performance testing with controlled response times and failure scenarios
  • [4]Contract testing between API consumers and providers during parallel development
  • [5]Demo environments where real services are unavailable or expensive to run
  • [6]CI/CD pipelines requiring predictable API responses for automated testing
  • [7]Training and development environments simulating production API behaviors

[!]Prerequisites

  • [!]Docker Engine 20.10+ and Docker Compose V2 for container orchestration
  • [!]Minimum 512MB RAM allocation for WireMock JVM and request processing
  • [!]Port 8080 available on host system for WireMock HTTP interface
  • [!]Local filesystem permissions for creating ./wiremock/mappings and ./wiremock/__files directories
  • [!]Basic understanding of HTTP request/response structure and JSON formatting
  • [!]Familiarity with REST API concepts for creating effective mock definitions
[!]

WARNING: For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

[$]docker-compose.yml

[docker-compose.yml]
1services: 
2  wiremock: 
3    image: wiremock/wiremock:latest
4    container_name: wiremock
5    restart: unless-stopped
6    volumes: 
7      - ./wiremock/mappings:/home/wiremock/mappings
8      - ./wiremock/__files:/home/wiremock/__files
9    ports: 
10      - "8080:8080"
11    command: --verbose

[$].env Template

[.env]
1# Create stubs in ./wiremock/mappings

[i]Usage Notes

  1. [1]Docs: https://wiremock.org/docs/
  2. [2]API at http://localhost:8080 - serves mocked endpoints
  3. [3]Admin API at /__admin for dynamic stub creation
  4. [4]Define stubs in ./wiremock/mappings as JSON files
  5. [5]Record mode: --record-mappings to capture real API responses
  6. [6]Fault injection, delays, and stateful scenarios supported

[>]Quick Start

[terminal]
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  wiremock:
5    image: wiremock/wiremock:latest
6    container_name: wiremock
7    restart: unless-stopped
8    volumes:
9      - ./wiremock/mappings:/home/wiremock/mappings
10      - ./wiremock/__files:/home/wiremock/__files
11    ports:
12      - "8080:8080"
13    command: --verbose
14EOF
15
16# 2. Create the .env file
17cat > .env << 'EOF'
18# Create stubs in ./wiremock/mappings
19EOF
20
21# 3. Start the services
22docker compose up -d
23
24# 4. View logs
25docker compose logs -f

[>]One-Liner

Run this command to download and set up the recipe in one step:

[terminal]
1curl -fsSL https://docker.recipes/api/recipes/wiremock/run | bash

[?]Troubleshooting

  • [!]WireMock returns 404 for all requests: Verify JSON mapping files exist in ./wiremock/mappings with valid request matching patterns
  • [!]Container fails to start with permission denied: Ensure Docker has read/write access to local wiremock directories or adjust file ownership
  • [!]Admin API returns connection refused: Check that requests target /__admin path and port 8080 is properly mapped
  • [!]Mapping files not loading on container restart: Validate JSON syntax in mapping files using a JSON linter before mounting
  • [!]Static file responses return 404: Confirm files are placed in ./wiremock/__files directory and referenced correctly in mapping bodyFileName
  • [!]Request matching too broad or narrow: Review urlPattern versus urlPathPattern usage and header matching case sensitivity

Community Notes

Loading...
Loading notes...

## Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

## Components

wiremock

## Tags

#wiremock#mocking#api#testing

## Category

Development Tools

## Related