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

# Properties

> Configure MockServer using property files, system properties, environment variables, or Java code.

MockServer reads configuration from four sources. When the same property is set in multiple places, the source with the highest precedence wins:

1. **Java code** (highest precedence)
2. **System property** (e.g. `-Dmockserver.logLevel=DEBUG`)
3. **Property file** (defaults to `mockserver.properties` in the working directory)
4. **Environment variable** (lowest precedence)

## Property file

By default MockServer looks for a file named `mockserver.properties` in the current working directory. Override this location with the `mockserver.propertyFile` system property:

```bash theme={null}
java -Dmockserver.propertyFile=/config/mockserver.properties -jar mockserver.jar -serverPort 1080
```

Or with the environment variable:

```bash theme={null}
MOCKSERVER_PROPERTY_FILE=/config/mockserver.properties
```

A property file uses standard Java `.properties` format:

```properties theme={null}
# mockserver.properties

# Port
mockserver.serverPort=1080

# Log level
mockserver.logLevel=INFO

# Memory limits
mockserver.maxExpectations=5000
mockserver.maxLogEntries=60000

# Initialization
mockserver.initializationJsonPath=expectations.json
mockserver.watchInitializationJson=false

# Persistence
mockserver.persistExpectations=false
# mockserver.persistedExpectationsPath=persistedExpectations.json

# CORS
mockserver.enableCORSForAPI=false
mockserver.enableCORSForAllResponses=false
```

## Key properties

<AccordionGroup>
  <Accordion title="Server port">
    The HTTP, HTTPS, SOCKS, and HTTP CONNECT port(s) for both mocking and proxying. Accepts a comma-separated list to listen on multiple ports.

    |         | Value                         |
    | ------- | ----------------------------- |
    | Default | *(required — no default)*     |
    | Type    | `int` or comma-separated list |

    <CodeGroup>
      ```java Java theme={null}
      ConfigurationProperties.mockServerPort(1080);
      ```

      ```bash System property theme={null}
      -Dmockserver.serverPort=1080
      ```

      ```bash Environment variable theme={null}
      MOCKSERVER_SERVER_PORT=1080
      ```

      ```properties Property file theme={null}
      mockserver.serverPort=1080
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Log level">
    The minimum level of logs to record in the event log and output to stdout. Lower log levels produce more output. The default is `INFO`.

    Accepted values: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `OFF`

    |         | Value    |
    | ------- | -------- |
    | Default | `INFO`   |
    | Type    | `string` |

    <Note>
      You can change the log level at any time without restarting MockServer.
    </Note>

    <CodeGroup>
      ```java Java theme={null}
      ConfigurationProperties.logLevel("DEBUG");
      ```

      ```bash System property theme={null}
      -Dmockserver.logLevel=DEBUG
      ```

      ```bash Environment variable theme={null}
      MOCKSERVER_LOG_LEVEL=DEBUG
      ```

      ```properties Property file theme={null}
      mockserver.logLevel=DEBUG
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Maximum expectations">
    The maximum number of expectations held in the in-memory ring buffer. When this limit is reached, the oldest expectations are overwritten.

    |         | Value                       |
    | ------- | --------------------------- |
    | Default | free heap space in KB / 400 |
    | Type    | `int`                       |

    <CodeGroup>
      ```java Java theme={null}
      ConfigurationProperties.maxExpectations(5000);
      ```

      ```bash System property theme={null}
      -Dmockserver.maxExpectations=5000
      ```

      ```bash Environment variable theme={null}
      MOCKSERVER_MAX_EXPECTATIONS=5000
      ```

      ```properties Property file theme={null}
      mockserver.maxExpectations=5000
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Maximum log entries">
    The maximum number of log entries held in memory. This includes recorded requests, expectation match failures, and other log entries. Lower log levels produce more log entries, particularly at `TRACE`.

    |         | Value                      |
    | ------- | -------------------------- |
    | Default | free heap space in KB / 30 |
    | Type    | `int`                      |

    <CodeGroup>
      ```java Java theme={null}
      ConfigurationProperties.maxLogEntries(60000);
      ```

      ```bash System property theme={null}
      -Dmockserver.maxLogEntries=60000
      ```

      ```bash Environment variable theme={null}
      MOCKSERVER_MAX_LOG_ENTRIES=60000
      ```

      ```properties Property file theme={null}
      mockserver.maxLogEntries=60000
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="CORS allowed origins">
    Controls the `Access-Control-Allow-Origin` header for CORS responses. Set `enableCORSForAPI` to allow cross-origin requests to the MockServer REST API, or `enableCORSForAllResponses` to enable CORS on all responses including expectation responses.

    <CodeGroup>
      ```java Java theme={null}
      ConfigurationProperties.enableCORSForAPI(true);
      ConfigurationProperties.enableCORSForAllResponses(true);
      ```

      ```bash System property theme={null}
      -Dmockserver.enableCORSForAPI=true
      -Dmockserver.enableCORSForAllResponses=true
      ```

      ```bash Environment variable theme={null}
      MOCKSERVER_ENABLE_CORS_FOR_API=true
      MOCKSERVER_ENABLE_CORS_FOR_ALL_RESPONSES=true
      ```

      ```properties Property file theme={null}
      mockserver.enableCORSForAPI=true
      mockserver.enableCORSForAllResponses=true
      ```
    </CodeGroup>

    You can also customize the allowed headers and methods:

    ```properties theme={null}
    mockserver.corsAllowHeaders=Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization
    mockserver.corsAllowMethods=CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE
    mockserver.corsAllowCredentials=false
    mockserver.corsMaxAgeInSeconds=300
    ```
  </Accordion>

  <Accordion title="Initialization JSON path">
    The path to a JSON file used to pre-load expectations when MockServer starts. The file must contain a JSON array of expectations in the REST API format.

    |         | Value    |
    | ------- | -------- |
    | Default | `null`   |
    | Type    | `string` |

    <CodeGroup>
      ```java Java theme={null}
      ConfigurationProperties.initializationJsonPath("expectations.json");
      ```

      ```bash System property theme={null}
      -Dmockserver.initializationJsonPath=expectations.json
      ```

      ```bash Environment variable theme={null}
      MOCKSERVER_INITIALIZATION_JSON_PATH=expectations.json
      ```

      ```properties Property file theme={null}
      mockserver.initializationJsonPath=expectations.json
      ```
    </CodeGroup>

    Enable `watchInitializationJson` to have MockServer reload expectations automatically when the file changes:

    ```properties theme={null}
    mockserver.watchInitializationJson=true
    ```
  </Accordion>
</AccordionGroup>

## Programmatic configuration (Java)

When running MockServer in-process, set properties using the static `ConfigurationProperties` class or a per-instance `Configuration` object.

`ConfigurationProperties` is JVM-global and stores values as system properties:

```java theme={null}
import org.mockserver.configuration.ConfigurationProperties;

// Set before starting MockServer
ConfigurationProperties.logLevel("DEBUG");
ConfigurationProperties.maxExpectations(2000);
ConfigurationProperties.initializationJsonPath("expectations.json");
```

`Configuration` is scoped to a single MockServer instance and is passed to the constructor:

```java theme={null}
import org.mockserver.configuration.Configuration;
import org.mockserver.integration.ClientAndServer;

Configuration config = Configuration.configuration()
    .logLevel(Level.DEBUG)
    .maxExpectations(2000);

ClientAndServer mockServer = ClientAndServer.startClientAndServer(config, 1080);
```

<Note>
  `Configuration` falls back to `ConfigurationProperties` for any values you have not explicitly set.
</Note>

## Docker and environment variables

When running MockServer in Docker, use environment variables to configure it without modifying files:

```yaml theme={null}
services:
  mockserver:
    image: mockserver/mockserver:latest
    ports:
      - "1080:1080"
    environment:
      MOCKSERVER_SERVER_PORT: "1080"
      MOCKSERVER_LOG_LEVEL: "INFO"
      MOCKSERVER_MAX_EXPECTATIONS: "5000"
      MOCKSERVER_INITIALIZATION_JSON_PATH: /config/expectations.json
    volumes:
      - ./config:/config
```

<Tip>
  Properties that control startup behavior (such as port and initialization file) must be set before MockServer starts. Properties like `logLevel` can be changed at runtime.
</Tip>