Skip to main content
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: 
java -Dmockserver.propertyFile=/config/mockserver.properties -jar mockserver.jar -serverPort 1080
Or with the environment variable: 
MOCKSERVER_PROPERTY_FILE=/config/mockserver.properties
A property file uses standard Java .properties format: 
# 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

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)
Typeint or comma-separated list
ConfigurationProperties.mockServerPort(1080);
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
DefaultINFO
Typestring
You can change the log level at any time without restarting MockServer.
ConfigurationProperties.logLevel("DEBUG");
The maximum number of expectations held in the in-memory ring buffer. When this limit is reached, the oldest expectations are overwritten.
Value
Defaultfree heap space in KB / 400
Typeint
ConfigurationProperties.maxExpectations(5000);
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
Defaultfree heap space in KB / 30
Typeint
ConfigurationProperties.maxLogEntries(60000);
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.
ConfigurationProperties.enableCORSForAPI(true);
ConfigurationProperties.enableCORSForAllResponses(true);
You can also customize the allowed headers and methods:
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
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
Defaultnull
Typestring
ConfigurationProperties.initializationJsonPath("expectations.json");
Enable watchInitializationJson to have MockServer reload expectations automatically when the file changes:
mockserver.watchInitializationJson=true

​
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: 
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: 
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);
Configuration falls back to ConfigurationProperties for any values you have not explicitly set.

​
Docker and environment variables

When running MockServer in Docker, use environment variables to configure it without modifying files: 
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
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.