MockServer is available as a docker container that allows you to easily run MockServer as a separate container on any environment without having to install Java or any other libraries. The docker container fully encapsulates all requirements required to run MockServer (such as Java) and separates the running MockServer instance from all other parts of the system.

MockServer docker container can be found at MockServer Docker

Running MockServer Docker Container

The typical sequence for running the MockServer docker image is as follows:
  1. Install Docker
  2. Pull (or Update) Image
  3. Run Container
In addition it is possible to customise how the container is run.  

Install Docker

To install Docker see the installation instructions.

 

Pull MockServer Image

To pull the MockServer Docker image use the pull command, as follows:

docker pull mockserver/mockserver

MockServer images are also available from AWS ECR Public, which avoids Docker Hub rate limits and provides lower latency for AWS-based CI/CD:

docker pull public.ecr.aws/mockserver/mockserver

This is not strictly necessary as the image will be automatically pulled if it does not exist when the run command is used. However, using the pull command will ensure the latest version of the image is downloaded.

 

Run MockServer Container

Then to run MockServer as a Docker container run the following command:

docker run -d --rm -P mockserver/mockserver

The -P switch in this command tells Docker to map all ports exported by the MockServer container to dynamically allocated ports on the host machine.

To view information about the MockServer container, including which dynamic ports have been used run the following command:

docker ps

No Interactive Shell

MockServer uses distroless as its based container for both size and security and so does not contain an interactive shell. This minimises the likelihood of vulnerabilities and to reduces the attack surface by ensuring only the JVM and MockServer code is inside the container.

   

Configure Port Mapping

This MockServer docker container exports the following port:

  • serverPort 1080

To specify which ports (on the host machine) should be mapped to the MockServer docker container use the -p <host port>:<container port> option, as follows:

docker run -d --rm -p <serverPort>:1080 mockserver/mockserver

For example:

docker run -d --rm -p 1080:1080 mockserver/mockserver
 

Environment Variables

It is possible configure MockServer behaviour through environment variables, this includes port mappings, log level and lots of other properties for example:

docker run -d --rm -p 1090:1090 --env MOCKSERVER_LOG_LEVEL=TRACE --env MOCKSERVER_SERVER_PORT=1090 mockserver/mockserver
 

JVM Heap Size

The default JVM heap size in the Docker container is determined by the JVM's container-aware defaults (typically 25% of the container's memory limit). For high-throughput use cases or large response bodies, you may need to increase the heap size using JAVA_TOOL_OPTIONS:

docker run -d --rm -p 1080:1080 --env JAVA_TOOL_OPTIONS="-Xmx512m" mockserver/mockserver

If MockServer becomes slow or unresponsive under sustained load, see the troubleshooting guide for recommended memory and logging configuration.

 

Modifying Default Command

The MockServer container entrypoint calls org.mockserver.cli.Main directly with CMD [] (no default arguments). The SERVER_PORT environment variable defaults to 1080 in the Dockerfile. Command line options can be explicitly provided, for example:

docker run --rm --name mockserver -p 1080:1090 mockserver/mockserver -logLevel INFO -serverPort 1090 -proxyRemotePort 443 -proxyRemoteHost mock-server.com

Detailed MockServer Configuration

To support configuring MockServer a mockserver.properties will be loaded from /config directory if it exists.

A mockserver.properties configuration file and other related configuration files such as json expectation initialization, or custom TLS CA, X.509 Certificate or Private Key should be mapping into the /config directory.

For example to add configuration files in the current directory, such as mockserver.properties, map $(pwd) into /config, as follows: 
docker run -v $(pwd):/config -p 1080:1080  mockserver/mockserver -serverPort 1080

See MockServer Configuration for details of all configuration options.

As the Docker image is based from gcr.io/distroless/java17:nonroot and the user nonroot is used, we need to configure permissions in order to allow the user in the container read/write files in mounted volumes: 
chmod o+r $(pwd)/mockserver.properties
 

Extending MockServer Classpath

To use class callbacks or an expectation initializer class the classpath for MockServer must include the specified classes.

To support adding classes to the classpath any jar files contained in the /libs directory will be added into MockServer classpath.

For example to add all jar files in the current directory, map $(pwd) into /libs, as follows: 
docker run -v $(pwd):/libs -p 1080:1080  mockserver/mockserver -serverPort 1080
 

Docker Health Checks

MockServer Docker images include a built-in HEALTHCHECK instruction that uses a lightweight Java health check class to verify the server is running. Since the images are based on distroless containers (no shell, no curl), the health check runs as a small Java process that calls the PUT /mockserver/status endpoint internally.

The built-in health check works automatically with no configuration required:

HEALTHCHECK --interval=10s --timeout=5s --start-period=120s --retries=3
  CMD ["java", "-cp", "/mockserver-netty-jar-with-dependencies.jar", "org.mockserver.cli.HealthCheck"]

The health check reads the SERVER_PORT or MOCKSERVER_SERVER_PORT environment variable to determine the correct port (defaults to 1080). Docker reports the container as healthy once MockServer is ready to accept requests.

Using with Docker Compose

The built-in health check integrates with Docker Compose depends_on conditions:

services:
  mockserver:
    image: mockserver/mockserver:5.15.0
    ports:
      - "1080:1080"

  app:
    image: my-app:latest
    depends_on:
      mockserver:
        condition: service_healthy

To override or disable the built-in health check, use the healthcheck key in your Compose file.

Kubernetes Liveness and Readiness Probes

In Kubernetes, use httpGet probes with the configurable liveness endpoint:

containers:
  - name: mockserver
    image: mockserver/mockserver:5.15.0
    ports:
      - containerPort: 1080
    env:
      - name: MOCKSERVER_LIVENESS_HTTP_GET_PATH
        value: "/liveness/probe"
    livenessProbe:
      httpGet:
        path: /liveness/probe
        port: 1080
      initialDelaySeconds: 10
      periodSeconds: 5
    readinessProbe:
      httpGet:
        path: /liveness/probe
        port: 1080
      initialDelaySeconds: 5
      periodSeconds: 5

The MockServer Helm chart configures these probes automatically.

Amazon ECS Health Check

For ECS task definitions, the built-in HEALTHCHECK in the Docker image is used automatically. Alternatively, configure an explicit health check:

{
  "containerDefinitions": [{
    "name": "mockserver",
    "image": "mockserver/mockserver:5.15.0",
    "healthCheck": {
      "command": ["CMD-SHELL", "curl -f http://localhost:1080/mockserver/status -X PUT || exit 1"],
      "interval": 10,
      "timeout": 5,
      "retries": 3,
      "startPeriod": 120
    }
  }]
}

Note: The ECS CMD-SHELL health check runs on the host, not inside the distroless container, so curl is available.

For more information on the liveness endpoint configuration, see liveness configuration properties.

 

Docker Compose

MockServer can be run using docker compose by adding the container as a service.

The MockServer container uses an entrypoint, so it is possible to configure the MockServer by specifying the command line flags using by specifying the command, as follows:

services:
  mockServer:
    image: mockserver/mockserver:5.15.0
    command: -logLevel DEBUG -serverPort 1090 -proxyRemotePort 80 -proxyRemoteHost www.mock-server.com
    ports:
      - 1080:1090

It is also possible to configure the MockServer by setting environment variables, as follows:

services:
  mockServer:
    image: mockserver/mockserver:5.15.0
    ports:
      - 1080:1090
    environment:
      MOCKSERVER_MAX_EXPECTATIONS: 100
      MOCKSERVER_MAX_HEADER_SIZE: 8192

It is also possible to configure the MockServer by mounting a volume containing a properties file or JSON expectation initializer, as follows:

services:
  mockServer:
    image: mockserver/mockserver:5.15.0
    ports:
      - 1080:1080
    environment:
      MOCKSERVER_PROPERTY_FILE: /config/mockserver.properties
      MOCKSERVER_INITIALIZATION_JSON_PATH: /config/initializerJson.json
    volumes:
      - type: bind
        source: .
        target: /config

To initialise MockServer using an OpenAPI specification file, mount the file and set the MOCKSERVER_INITIALIZATION_OPENAPI_PATH environment variable:

services:
  mockServer:
    image: mockserver/mockserver:5.15.0
    ports:
      - 1080:1080
    environment:
      MOCKSERVER_INITIALIZATION_OPENAPI_PATH: /config/petstore.yaml
    volumes:
      - type: bind
        source: .
        target: /config