The typical sequence for running the MockServer docker image is as follows:

<ol>
	<li><a href="#install_docker">Install Docker</a></li>
	<li><a href="#pull_docker_image">Pull (or Update) Image</a></li>
	<li><a href="#run_docker_container">Run Container</a></li>
</ol>

In addition it is possible to <a href="#docker_container_customization">customise how the container is run</a>.

<a id="install_docker" class="anchor" href="#install_docker">&nbsp;</a>

<h3>Install Docker</h3>

<p>To install Docker see the <a target="_blank" href="https://docs.docker.com/installation/" rel="noopener noreferrer">installation instructions</a>.</p>

<a id="pull_docker_image" class="anchor" href="#pull_docker_image">&nbsp;</a>

<h3>Pull MockServer Image</h3>

<p>To pull the MockServer Docker image use the pull command, as follows:</p>

<pre><code class="code">docker pull mockserver/mockserver</code></pre>

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

<pre><code class="code">docker pull public.ecr.aws/mockserver/mockserver</code></pre>

<p>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.</p>

<a id="run_docker_container" class="anchor" href="#run_docker_container">&nbsp;</a>

<h3>Run MockServer Container</h3>

<p>Then to run MockServer as a Docker container run the following command:</p>

<pre><code class="code">docker run -d --rm -P mockserver/mockserver</code></pre>

<p>The <strong>-P</strong> switch in this command tells Docker to map all ports exported by the MockServer container to dynamically allocated ports on the host machine.</p><p>To view information about the MockServer container, including which dynamic ports have been used run the following command:</p>

<pre><code class="code">docker ps</code></pre>

<h3>No Interactive Shell</h3>

<p>MockServer uses <a target="_blank" href="https://github.com/GoogleContainerTools/distroless" rel="noopener noreferrer">distroless</a> 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.</p>

<a id="docker_detailed_configuration" class="anchor" href="#docker_detailed_configuration">&nbsp;</a>

<a id="docker_container_customization" class="anchor" href="#docker_container_customization">&nbsp;</a>

<h3>Configure Port Mapping</h3>

<p>This MockServer docker container exports the following port:</p>

<ul>
	<li><strong>serverPort</strong> 1080</li>
</ul>

<p>To specify which ports (on the host machine) should be mapped to the MockServer docker container use the <strong>-p</strong> <span class="command_line_argument_placeholder">&lt;host port&gt;</span><strong>:</strong><span class="command_line_argument_placeholder">&lt;container port&gt;</span> option, as follows:</p>

<pre><code class="code">docker run -d --rm -p <span class="command_line_argument_placeholder">&lt;serverPort&gt;</span>:<span class="numeric_literal">1080</span> mockserver/mockserver</code></pre>

<p>For example:</p>

<pre><code class="code">docker run -d --rm -p <span class="numeric_literal">1080</span>:<span class="numeric_literal">1080</span> mockserver/mockserver</code></pre>

<a id="docker_container_environment_variables" class="anchor" href="#docker_container_environment_variables">&nbsp;</a>

<h3>Environment Variables</h3>

<p>It is possible configure MockServer behaviour through environment variables, this includes port mappings, log level and lots of <a href="/mock_server/configuration_properties.html">other properties</a> for example:</p>

<pre><code class="code">docker run -d --rm -p <span class="numeric_literal">1090</span>:<span class="numeric_literal">1090</span> --env <span class="annotation">MOCKSERVER_LOG_LEVEL</span>=<span class="string_literal">TRACE</span> --env <span class="annotation">MOCKSERVER_SERVER_PORT</span>=<span class="numeric_literal">1090</span> mockserver/mockserver</code></pre>

<a id="docker_heap_sizing" class="anchor" href="#docker_heap_sizing">&nbsp;</a>

<h3>JVM Heap Size</h3>

<p>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 <span class="inline_code">JAVA_TOOL_OPTIONS</span>:</p>

<pre><code class="code">docker run -d --rm -p <span class="numeric_literal">1080</span>:<span class="numeric_literal">1080</span> --env <span class="annotation">JAVA_TOOL_OPTIONS</span>=<span class="string_literal">"-Xmx512m"</span> mockserver/mockserver</code></pre>

<p>If MockServer becomes slow or unresponsive under sustained load, see the <a href="/mock_server/performance.html#troubleshooting_performance">troubleshooting guide</a> for recommended memory and logging configuration.</p>

<a id="docker_container_default_command" class="anchor" href="#docker_container_default_command">&nbsp;</a>

<h3>Modifying Default Command</h3>

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

<pre><code class="code">docker run --rm --name mockserver -p <span class="numeric_literal">1080</span>:<span class="numeric_literal">1090</span> mockserver/mockserver <em>-logLevel <span class="string_literal">INFO</span> -serverPort <span class="numeric_literal">1090</span> -proxyRemotePort <span class="numeric_literal">443</span> -proxyRemoteHost <span class="string_literal">mock-server.com</span></em></code></pre>

<h2>Detailed MockServer Configuration</h2>

<p>To support configuring MockServer a <strong>mockserver.properties</strong> will be loaded from <strong>/config</strong> directory if it exists.</p>
<p>A <strong>mockserver.properties</strong> configuration file and other related configuration files such as <a href="/mock_server/initializing_expectations.html">json expectation initialization</a>, or custom <a href="/mock_server/HTTPS_TLS.html#configuration">TLS CA, X.509 Certificate or Private Key</a> should be mapping into the <strong>/config</strong> directory.</p>

For example to add configuration files in the current directory, such as <strong>mockserver.properties</strong>, map <strong>$(pwd)</strong> into <strong>/config</strong>, as follows:

<pre><code class="code">docker run -v $(pwd):/config -p <span class="numeric_literal">1080</span>:<span class="numeric_literal">1080</span>  mockserver/mockserver -serverPort <span class="numeric_literal">1080</span></code></pre>

<p>See <a href="/mock_server/configuration_properties.html">MockServer Configuration</a> for details of all configuration options.</p>

As the <a target="_blank" href="https://github.com/mock-server/mockserver-monorepo/blob/master/docker/Dockerfile" rel="noopener noreferrer">Docker image is based from <strong>gcr.io/distroless/java17:nonroot</strong></a> and the user <strong>nonroot</strong> is used, we need to configure permissions in order to allow the user in the container read/write files in mounted volumes:

<pre><code class="code">chmod o+r $(pwd)/mockserver.properties</code></pre>

<a id="docker_extend_classpath" class="anchor" href="#docker_extend_classpath">&nbsp;</a>

<h2>Extending MockServer Classpath</h2>

<p>To use <a href="/mock_server/creating_expectations.html#button_response_class_callback">class callbacks</a> or an <a href="/mock_server/initializing_expectations.html#expectation_initializer_class">expectation initializer class</a> the classpath for MockServer must include the specified classes.</p>
<p>To support adding classes to the classpath any jar files contained in the <strong>/libs</strong> directory will be added into MockServer classpath.</p>

For example to add all jar files in the current directory, map <strong>$(pwd)</strong> into <strong>/libs</strong>, as follows:

<pre><code class="code">docker run -v $(pwd):/libs -p <span class="numeric_literal">1080</span>:<span class="numeric_literal">1080</span>  mockserver/mockserver -serverPort <span class="numeric_literal">1080</span></code></pre>

<a id="docker_healthcheck" class="anchor" href="#docker_healthcheck">&nbsp;</a>

<h2>Docker Health Checks</h2>

<p>MockServer Docker images include a built-in <span class="inline_code">HEALTHCHECK</span> instruction that uses a lightweight Java health check class to verify the server is running. Since the images are based on <a target="_blank" href="https://github.com/GoogleContainerTools/distroless" rel="noopener noreferrer">distroless</a> containers (no shell, no <code>curl</code>), the health check runs as a small Java process that calls the <span class="inline_code">PUT /mockserver/status</span> endpoint internally.</p>

<p>The built-in health check works automatically with no configuration required:</p>

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

<p>The health check reads the <span class="inline_code">SERVER_PORT</span> or <span class="inline_code">MOCKSERVER_SERVER_PORT</span> environment variable to determine the correct port (defaults to 1080). Docker reports the container as <span class="inline_code">healthy</span> once MockServer is ready to accept requests.</p>

<h3>Using with Docker Compose</h3>

<p>The built-in health check integrates with Docker Compose <span class="inline_code">depends_on</span> conditions:</p>

<pre class="prettyprint lang-yaml code"><code class="code">services:
  mockserver:
    image: mockserver/mockserver:{{ site.mockserver_version }}
    ports:
      - "1080:1080"

  app:
    image: my-app:latest
    depends_on:
      mockserver:
        condition: service_healthy</code></pre>

<p>To override or disable the built-in health check, use the <span class="inline_code">healthcheck</span> key in your Compose file.</p>

<h3>Kubernetes Liveness and Readiness Probes</h3>

<p>In Kubernetes, use <span class="inline_code">httpGet</span> probes with the configurable liveness endpoint:</p>

<pre class="prettyprint lang-yaml code"><code class="code">containers:
  - name: mockserver
    image: mockserver/mockserver:{{ site.mockserver_version }}
    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</code></pre>

<p>The MockServer Helm chart configures these probes automatically.</p>

<h3>Amazon ECS Health Check</h3>

<p>For ECS task definitions, the built-in <span class="inline_code">HEALTHCHECK</span> in the Docker image is used automatically. Alternatively, configure an explicit health check:</p>

<pre class="prettyprint lang-json code"><code class="code">{
  "containerDefinitions": [{
    "name": "mockserver",
    "image": "mockserver/mockserver:{{ site.mockserver_version }}",
    "healthCheck": {
      "command": ["CMD-SHELL", "curl -f http://localhost:1080/mockserver/status -X PUT || exit 1"],
      "interval": 10,
      "timeout": 5,
      "retries": 3,
      "startPeriod": 120
    }
  }]
}</code></pre>

<p><strong>Note:</strong> The ECS <span class="inline_code">CMD-SHELL</span> health check runs on the host, not inside the distroless container, so <span class="inline_code">curl</span> is available.</p>

<p>For more information on the liveness endpoint configuration, see <a href="/mock_server/configuration_properties.html#liveness_configuration">liveness configuration properties</a>.</p>

<p>A selection of commonly used environment variables is shown in the Docker Compose examples below. <code>MOCKSERVER_MAX_LLM_CONVERSATION_BODY_SIZE</code> controls the maximum request body size that conversation-aware LLM matchers will parse (default 1 MiB; valid range 16 KiB&ndash;64 MiB). See <a href="/mock_server/performance.html#button_configuration_max_llm_conversation_body_size">Performance Configuration</a> for details.</p>

<a id="docker_compose" class="anchor" href="#docker_compose">&nbsp;</a>

<h2>Docker Compose</h2>

<p>MockServer can be run using <a target="_blank" href="https://docs.docker.com/compose/" rel="noopener noreferrer">docker compose</a> by adding the container as a service.</p>

<p>The MockServer container uses an <span class="keyword">entrypoint</span>, so it is possible to configure the MockServer by specifying the command line flags using by specifying the <span class="keyword">command</span>, as follows:</p>

<pre class="prettyprint lang-yaml code"><code class="code">services:
  mockServer:
    image: mockserver/mockserver:{{ site.mockserver_version }}
    command: -logLevel DEBUG -serverPort 1090 -proxyRemotePort 80 -proxyRemoteHost www.mock-server.com
    ports:
      - 1080:1090</code></pre>

<p>It is also possible to configure the MockServer by setting <span class="keyword">environment</span> variables, as follows:</p>

<pre class="prettyprint lang-yaml code"><code class="code">services:
  mockServer:
    image: mockserver/mockserver:{{ site.mockserver_version }}
    ports:
      - 1080:1090
    environment:
      MOCKSERVER_MAX_EXPECTATIONS: 100
      MOCKSERVER_MAX_HEADER_SIZE: 8192
      MOCKSERVER_MAX_LLM_CONVERSATION_BODY_SIZE: 1048576</code></pre>

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

<pre class="prettyprint lang-yaml code"><code class="code">services:
  mockServer:
    image: mockserver/mockserver:{{ site.mockserver_version }}
    ports:
      - 1080:1080
    environment:
      MOCKSERVER_PROPERTY_FILE: /config/mockserver.properties
      MOCKSERVER_INITIALIZATION_JSON_PATH: /config/initializerJson.json
    volumes:
      - type: bind
        source: .
        target: /config</code></pre>

<p>To initialise MockServer using an OpenAPI specification file, mount the file and set the <strong>MOCKSERVER_INITIALIZATION_OPENAPI_PATH</strong> environment variable:</p>

<pre class="prettyprint lang-yaml code"><code class="code">services:
  mockServer:
    image: mockserver/mockserver:{{ site.mockserver_version }}
    ports:
      - 1080:1080
    environment:
      MOCKSERVER_INITIALIZATION_OPENAPI_PATH: /config/petstore.yaml
    volumes:
      - type: bind
        source: .
        target: /config</code></pre>
