> ## Documentation Index
> Fetch the complete documentation index at: https://moeck.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Running MockServer

> Deploy MockServer via Docker, Helm, Maven, npm, standalone JAR, JUnit 4/5, or Spring.

MockServer supports multiple deployment options. Choose the one that fits your environment.

<Note>
  All deployment options (except the deployable WAR) use a single port for HTTP, HTTPS, and SOCKS traffic via port unification. You do not need to configure separate ports for different protocols.
</Note>

<Tabs>
  <Tab title="Docker">
    Run MockServer as a Docker container:

    ```bash theme={null}
    docker run -d --rm -p 1080:1080 mockserver/mockserver
    ```

    MockServer is now available at `http://localhost:1080`.

    **Configure via environment variables**

    Pass configuration options as environment variables:

    ```bash theme={null}
    docker run -d --rm \
      -p 1090:1090 \
      --env MOCKSERVER_LOG_LEVEL=TRACE \
      --env MOCKSERVER_SERVER_PORT=1090 \
      mockserver/mockserver
    ```

    **Docker Compose**

    Add MockServer as a service in your `docker-compose.yml`:

    ```yaml theme={null}
    version: "2.4"
    services:
      mockServer:
        image: mockserver/mockserver:5.15.0
        ports:
          - 1080:1080
        environment:
          MOCKSERVER_MAX_EXPECTATIONS: 100
          MOCKSERVER_MAX_HEADER_SIZE: 8192
    ```

    To mount a properties file or JSON expectation initializer:

    ```yaml theme={null}
    version: "2.4"
    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
    ```

    <Note>
      MockServer uses a distroless base image (no interactive shell) for reduced attack surface. Only the JVM and MockServer code are included in the container.
    </Note>
  </Tab>

  <Tab title="Helm / Kubernetes">
    Deploy MockServer to any Kubernetes cluster using the official Helm chart.

    **Add the chart repository**

    ```bash theme={null}
    helm repo add mockserver https://www.mock-server.com
    helm repo update
    ```

    **Install the chart**

    ```bash theme={null}
    helm upgrade --install \
      --kube-context <your kube context> \
      --namespace mockserver \
      --create-namespace \
      --version 5.15.0 \
      mockserver mockserver/mockserver
    ```

    After installation, MockServer is available inside the cluster at `mockserver.mockserver.svc.cluster.local`.

    **Configure the deployment**

    Pass configuration values with `--set`:

    ```bash theme={null}
    helm upgrade --install \
      --namespace mockserver \
      --set app.serverPort=1080 \
      --set app.logLevel=INFO \
      mockserver mockserver/mockserver
    ```

    Supported values include:

    | Value                 | Default | Description                       |
    | --------------------- | ------- | --------------------------------- |
    | `app.serverPort`      | `1080`  | Port MockServer listens on        |
    | `app.logLevel`        | `INFO`  | Log verbosity                     |
    | `app.proxyRemoteHost` | —       | Host to forward proxy requests to |
    | `app.proxyRemotePort` | —       | Port to forward proxy requests to |
    | `app.jvmOptions`      | —       | Additional JVM options            |
    | `image.snapshot`      | `false` | Use the latest snapshot image     |

    **Check deployment status**

    ```bash theme={null}
    kubectl -n mockserver rollout status deployments mockserver
    ```

    **View logs**

    ```bash theme={null}
    kubectl -n mockserver logs --tail=100 -l app=mockserver,release=mockserver
    ```

    **Access from outside the cluster (port-forward)**

    ```bash theme={null}
    kubectl -n mockserver port-forward svc/mockserver 1080:1080 &
    export MOCKSERVER_HOST=127.0.0.1:1080
    ```

    **Remove the chart**

    ```bash theme={null}
    helm delete -n mockserver mockserver
    ```
  </Tab>

  <Tab title="Maven plugin">
    Use the Maven plugin to start MockServer automatically as part of your build lifecycle.

    Add the plugin to your `pom.xml`:

    ```xml theme={null}
    <plugin>
        <groupId>org.mock-server</groupId>
        <artifactId>mockserver-maven-plugin</artifactId>
        <version>5.15.0</version>
        <configuration>
            <serverPort>1080</serverPort>
            <logLevel>DEBUG</logLevel>
            <initializationClass>org.mockserver.maven.ExampleInitializationClass</initializationClass>
        </configuration>
        <executions>
            <execution>
                <id>process-test-classes</id>
                <phase>process-test-classes</phase>
                <goals>
                    <goal>start</goal>
                </goals>
            </execution>
            <execution>
                <id>verify</id>
                <phase>verify</phase>
                <goals>
                    <goal>stop</goal>
                </goals>
            </execution>
        </executions>
    </plugin>
    ```

    This starts MockServer in the `process-test-classes` phase and stops it in the `verify` phase, so your tests can use it during the `test` and `integration-test` phases.

    **Run from the command line**

    ```bash theme={null}
    mvn mockserver:run
    ```

    Or start MockServer as a forked JVM:

    ```bash theme={null}
    mvn -Dmockserver.serverPort=1080 -Dmockserver.logLevel=INFO \
      org.mock-server:mockserver-maven-plugin:5.15.0:runForked
    ```

    Stop the forked instance:

    ```bash theme={null}
    mvn -Dmockserver.serverPort=1080 \
      org.mock-server:mockserver-maven-plugin:5.15.0:stopForked
    ```

    <Warning>
      If you use the `runForked` goal and a test fails, Maven skips the `verify` phase, so MockServer will not be stopped. Use the `start` and `stop` goals instead to ensure MockServer always shuts down, even on test failures.
    </Warning>

    **Use the Java client API**

    To control MockServer programmatically, add the client dependency:

    ```xml theme={null}
    <dependency>
        <groupId>org.mock-server</groupId>
        <artifactId>mockserver-netty-no-dependencies</artifactId>
        <version>5.15.0</version>
    </dependency>
    ```

    Then start and stop MockServer in your test lifecycle:

    ```java theme={null}
    import static org.mockserver.integration.ClientAndServer.startClientAndServer;

    private ClientAndServer mockServer;

    @Before
    public void startMockServer() {
        mockServer = startClientAndServer(1080);
    }

    @After
    public void stopMockServer() {
        mockServer.stop();
    }
    ```
  </Tab>

  <Tab title="npm / Node.js">
    Install the npm module:

    ```bash theme={null}
    npm install mockserver-node --save-dev
    ```

    **Start and stop from Node.js**

    ```javascript theme={null}
    var mockserver = require('mockserver-node');

    mockserver.start_mockserver({
        serverPort: 1080,
        verbose: true,
        trace: true
    });

    // run tests

    mockserver.stop_mockserver({
        serverPort: 1080
    });
    ```

    **Grunt plugin**

    Add `start_mockserver` and `stop_mockserver` tasks to your `Gruntfile`:

    ```javascript theme={null}
    grunt.initConfig({
        start_mockserver: {
            start: {
                options: {
                    serverPort: 1080,
                    trace: true
                }
            }
        },
        stop_mockserver: {
            stop: {
                options: {
                    serverPort: 1080
                }
            }
        }
    });

    grunt.loadNpmTasks('mockserver-node');
    ```

    <Note>
      The request log is only captured when `trace: true` or `verbose: true` is set. You must enable one of these options to use the `/retrieve` endpoint for verification.
    </Note>
  </Tab>

  <Tab title="Standalone JAR">
    Download `mockserver-netty-no-dependencies-5.15.0.jar` from Maven Central, then run:

    ```bash theme={null}
    java -jar mockserver-netty-no-dependencies-5.15.0.jar -serverPort 1080
    ```

    **Available options**

    ```bash theme={null}
    java -jar mockserver-netty-no-dependencies-5.15.0.jar \
      -serverPort <port> \
      [-proxyRemotePort <port>] \
      [-proxyRemoteHost <hostname>] \
      [-logLevel <level>] \
      [-jvmOptions <system parameters>]
    ```

    | Option             | Required | Description                                                                                    |
    | ------------------ | -------- | ---------------------------------------------------------------------------------------------- |
    | `-serverPort`      | Yes      | HTTP, HTTPS, and SOCKS port(s). Supports comma-separated list for multiple ports.              |
    | `-proxyRemotePort` | No       | Enables port forwarding. Requests are forwarded to this port unless they match an expectation. |
    | `-proxyRemoteHost` | No       | Host for forwarded proxy requests. Defaults to `localhost` if not set.                         |
    | `-logLevel`        | No       | SLF4J levels: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `OFF`. Defaults to `INFO`.            |
    | `-jvmOptions`      | No       | Generic JVM options or system properties.                                                      |

    **Example — bind two ports with INFO logging**

    ```bash theme={null}
    java -jar mockserver-netty-no-dependencies-5.15.0.jar \
      -serverPort 1080,1081 \
      -logLevel INFO
    ```

    **Homebrew (macOS)**

    ```bash theme={null}
    brew install mockserver
    mockserver -serverPort 1080
    ```
  </Tab>

  <Tab title="JUnit 4">
    Add the JUnit 4 rule dependency:

    ```xml theme={null}
    <dependency>
        <groupId>org.mock-server</groupId>
        <artifactId>mockserver-junit-rule-no-dependencies</artifactId>
        <version>5.15.0</version>
    </dependency>
    ```

    Annotate a field in your test class with `@Rule`:

    ```java theme={null}
    @Rule
    public MockServerRule mockServerRule = new MockServerRule(this);

    private MockServerClient mockServerClient;
    ```

    `MockServerRule` starts MockServer on a free port before any test runs and stops it after all tests complete. An instance of `MockServerClient` is automatically assigned to any field of type `org.mockserver.client.MockServerClient`.

    **Constructor options**

    ```java theme={null}
    // Dynamically allocate a free port
    public MockServerRule(Object target);

    // Control whether one instance is shared per JVM or per test class
    public MockServerRule(Object target, boolean perTestSuite);

    // Bind to specific port(s)
    public MockServerRule(Object target, Integer... ports);
    ```
  </Tab>

  <Tab title="JUnit 5">
    Add the JUnit 5 extension dependency:

    ```xml theme={null}
    <dependency>
        <groupId>org.mock-server</groupId>
        <artifactId>mockserver-junit-jupiter-no-dependencies</artifactId>
        <version>5.15.0</version>
    </dependency>
    ```

    Annotate your test class with `@ExtendWith(MockServerExtension.class)`:

    ```java theme={null}
    @ExtendWith(MockServerExtension.class)
    class ExampleTestClass {
        private final ClientAndServer client;

        public ExampleTestClass(ClientAndServer client) {
            this.client = client;
        }

        @Test
        void testSomething() {
            // use client to create expectations and verify requests
        }
    }
    ```

    MockServer starts before any test runs and stops after all tests complete. A `MockServerClient` or `ClientAndServer` instance is injected via [JUnit 5 parameter resolution](https://junit.org/junit5/docs/current/user-guide/#extensions-parameter-resolution) into constructors, `@BeforeEach`/`@BeforeAll` methods, and test methods.

    **Bind to specific ports**

    Use `@MockServerSettings` to control which ports MockServer binds to:

    ```java theme={null}
    @ExtendWith(MockServerExtension.class)
    @MockServerSettings(ports = {8787, 8888})
    class ExampleTestClass {
        private final ClientAndServer client;

        public ExampleTestClass(ClientAndServer client) {
            this.client = client;
        }

        @Test
        void testSomething() {
            // ...
        }
    }
    ```
  </Tab>

  <Tab title="Spring">
    Add the Spring test listener dependency:

    ```xml theme={null}
    <dependency>
        <groupId>org.mock-server</groupId>
        <artifactId>mockserver-spring-test-listener-no-dependencies</artifactId>
        <version>5.15.0</version>
    </dependency>
    ```

    Annotate your test class with `@MockServerTest`:

    ```java theme={null}
    @MockServerTest
    @RunWith(SpringRunner.class)
    public class ExampleSpringTest {

        private MockServerClient mockServerClient;

        @Test
        public void testSomething() {
            // use mockServerClient to create expectations and verify requests
        }
    }
    ```

    The `mockserver-spring-test-listener` registers a Spring `TestExecutionListener` that starts MockServer on a free port when the test class is annotated with `@MockServerTest`. MockServer resets after each test and closes via a shutdown hook after all tests complete.

    **Inject the port into Spring properties**

    Use the `${mockServerPort}` placeholder to configure a Spring bean with the MockServer URL:

    ```java theme={null}
    @RunWith(SpringRunner.class)
    @MockServerTest("server.url=http://localhost:${mockServerPort}/path")
    @ContextConfiguration(classes = MyTestConfig.class)
    public class ExampleSpringTestWithUrl {

        @Autowired
        private MyClient client;

        private MockServerClient mockServerClient;

        @Test
        public void testSomething() {
            // ...
        }
    }
    ```

    **Inject the port directly**

    ```java theme={null}
    @MockServerTest
    @RunWith(SpringRunner.class)
    public class ExampleSpringTestWithPort {

        @MockServerPort
        Integer mockServerPort;

        @Test
        public void testSomething() {
            // ...
        }
    }
    ```

    <Warning>
      `@MockServerTest` does not support parallel test execution because the MockServer instance is shared across all test classes. To run tests in parallel, use a unique value in each request matcher to avoid conflicts.
    </Warning>
  </Tab>
</Tabs>