0
# Server Configuration
1

2
Comprehensive server management functionality for starting, configuring, and controlling WireMock instances with extensive configuration options including HTTP/HTTPS ports, SSL settings, proxy configuration, and performance tuning.
3

4
## Capabilities
5

6
### WireMockServer Class
7

8
Main server class that manages the HTTP server lifecycle and provides administrative capabilities.
9

10
```java { .api }
11
/**
12
 * Main WireMock server class implementing Container, Stubbing, and Admin interfaces
13
 */
14
class WireMockServer implements Container, Stubbing, Admin {
15
    /** Create server with custom options */
16
    WireMockServer(Options options);
17
    
18
    /** Create server with specific HTTP port */
19
    WireMockServer(int port);
20
    
21
    /** Create server with HTTP and HTTPS ports */
22
    WireMockServer(int port, Integer httpsPort, FileSource fileSource, 
23
                   boolean enableBrowserProxying, ProxySettings proxySettings, 
24
                   Notifier notifier);
25
    
26
    /** Start the server */
27
    void start();
28
    
29
    /** Stop the server gracefully */
30
    void stop();
31
    
32
    /** Get the HTTP port the server is running on */
33
    int port();
34
    
35
    /** Check if the server is currently running */
36
    boolean isRunning();
37
    
38
    /** Shutdown the server (alias for stop) */
39
    void shutdown();
40
}
41
```
42

43
**Usage Examples:**
44

45
```java
46
import com.github.tomakehurst.wiremock.WireMockServer;
47
import static com.github.tomakehurst.wiremock.core.WireMockConfiguration.wireMockConfig;
48

49
// Basic server on default port
50
WireMockServer server = new WireMockServer();
51
server.start();
52

53
// Server on specific port
54
WireMockServer server = new WireMockServer(8089);
55
server.start();
56

57
// Server with custom configuration
58
WireMockServer server = new WireMockServer(
59
    wireMockConfig()
60
        .port(8089)
61
        .httpsPort(8443)
62
        .keystorePath("keystore.jks")
63
        .keystorePassword("password")
64
);
65
server.start();
66

67
// Always stop server when done
68
server.stop();
69
```
70

71
### WireMockConfiguration Class
72

73
Configuration builder providing fluent API for all server options.
74

75
```java { .api }
76
/**
77
 * Configuration builder for WireMock server options
78
 */
79
class WireMockConfiguration implements Options {
80
    /** Create new configuration instance */
81
    static WireMockConfiguration wireMockConfig();
82
    
83
    /** Alias for wireMockConfig() */
84
    static WireMockConfiguration options();
85
    
86
    // Port Configuration
87
    /** Set HTTP port number */
88
    WireMockConfiguration port(int portNumber);
89
    
90
    /** Use dynamic port allocation */
91
    WireMockConfiguration dynamicPort();
92
    
93
    /** Set HTTPS port number */
94
    WireMockConfiguration httpsPort(Integer httpsPort);
95
    
96
    /** Use dynamic HTTPS port allocation */
97
    WireMockConfiguration dynamicHttpsPort();
98
    
99
    // Protocol Configuration
100
    /** Disable HTTP protocol */
101
    WireMockConfiguration httpDisabled(boolean httpDisabled);
102
    
103
    /** Disable HTTP/2 over plaintext */
104
    WireMockConfiguration http2PlainDisabled(boolean enabled);
105
    
106
    /** Disable HTTP/2 over TLS */
107
    WireMockConfiguration http2TlsDisabled(boolean enabled);
108
    
109
    // Server Configuration
110
    /** Set server bind address */
111
    WireMockConfiguration bindAddress(String bindAddress);
112
    
113
    /** Set container thread pool size */
114
    WireMockConfiguration containerThreads(Integer containerThreads);
115
    
116
    /** Set response timeout in milliseconds */
117
    WireMockConfiguration timeout(int timeout);
118
    
119
    // HTTPS/SSL Configuration
120
    /** Set keystore file path */
121
    WireMockConfiguration keystorePath(String path);
122
    
123
    /** Set keystore password */
124
    WireMockConfiguration keystorePassword(String keyStorePassword);
125
    
126
    /** Set key manager password */
127
    WireMockConfiguration keyManagerPassword(String keyManagerPassword);
128
    
129
    /** Set keystore type (JKS, PKCS12, etc.) */
130
    WireMockConfiguration keystoreType(String keyStoreType);
131
    
132
    /** Set truststore file path */
133
    WireMockConfiguration trustStorePath(String truststorePath);
134
    
135
    /** Set truststore password */
136
    WireMockConfiguration trustStorePassword(String trustStorePassword);
137
    
138
    /** Set truststore type */
139
    WireMockConfiguration trustStoreType(String trustStoreType);
140
    
141
    /** Require client certificate authentication */
142
    WireMockConfiguration needClientAuth(boolean needClientAuth);
143
    
144
    // File and Storage Configuration
145
    /** Set root directory for files */
146
    WireMockConfiguration withRootDirectory(String path);
147
    
148
    /** Set directory for response body files */
149
    WireMockConfiguration usingFilesUnderDirectory(String path);
150
    
151
    /** Use classpath files */
152
    WireMockConfiguration usingFilesUnderClasspath(String path);
153
    
154
    /** Set custom file source */
155
    WireMockConfiguration fileSource(FileSource fileSource);
156
    
157
    /** Set custom mappings source */
158
    WireMockConfiguration mappingSource(MappingsSource mappingsSource);
159
    
160
    /** Set filename template for generated files */
161
    WireMockConfiguration filenameTemplate(String filenameTemplate);
162
    
163
    // Jetty Server Configuration
164
    /** Set number of Jetty acceptor threads */
165
    WireMockConfiguration jettyAcceptors(Integer jettyAcceptors);
166
    
167
    /** Set Jetty accept queue size */
168
    WireMockConfiguration jettyAcceptQueueSize(Integer jettyAcceptQueueSize);
169
    
170
    /** Set maximum request header size */
171
    WireMockConfiguration jettyHeaderRequestSize(Integer jettyHeaderRequestSize);
172
    
173
    /** Set maximum response header size */
174
    WireMockConfiguration jettyHeaderResponseSize(Integer jettyHeaderResponseSize);
175
    
176
    /** Set Jetty stop timeout */
177
    WireMockConfiguration jettyStopTimeout(Long jettyStopTimeout);
178
    
179
    /** Set Jetty idle timeout */
180
    WireMockConfiguration jettyIdleTimeout(Long jettyIdleTimeout);
181
    
182
    // Performance Configuration
183
    /** Enable asynchronous response processing */
184
    WireMockConfiguration asynchronousResponseEnabled(boolean asynchronousResponseEnabled);
185
    
186
    /** Set number of asynchronous response threads */
187
    WireMockConfiguration asynchronousResponseThreads(int asynchronousResponseThreads);
188
    
189
    /** Set maximum HTTP client connections */
190
    WireMockConfiguration maxHttpClientConnections(int maxHttpClientConnections);
191
    
192
    /** Disable HTTP connection reuse */
193
    WireMockConfiguration disableConnectionReuse(boolean disableConnectionReuse);
194
    
195
    /** Set webhook thread pool size */
196
    WireMockConfiguration withWebhookThreadPoolSize(Integer webhookThreadPoolSize);
197
    
198
    // Response Configuration
199
    /** Set chunked transfer encoding policy */
200
    WireMockConfiguration useChunkedTransferEncoding(ChunkedEncodingPolicy policy);
201
    
202
    /** Disable gzip compression */
203
    WireMockConfiguration gzipDisabled(boolean gzipDisabled);
204
    
205
    /** Disable stub request logging */
206
    WireMockConfiguration stubRequestLoggingDisabled(boolean disabled);
207
    
208
    /** Enable CORS for stub responses */
209
    WireMockConfiguration stubCorsEnabled(boolean enabled);
210
    
211
    /** Set maximum logged response size */
212
    WireMockConfiguration maxLoggedResponseSize(int maxSize);
213
}
214
```
215

216
**Usage Examples:**
217

218
```java
219
import static com.github.tomakehurst.wiremock.core.WireMockConfiguration.wireMockConfig;
220

221
// Basic HTTP server
222
WireMockConfiguration config = wireMockConfig()
223
    .port(8089)
224
    .bindAddress("localhost");
225

226
// HTTPS enabled server
227
WireMockConfiguration httpsConfig = wireMockConfig()
228
    .port(8089)
229
    .httpsPort(8443)
230
    .keystorePath("/path/to/keystore.jks")
231
    .keystorePassword("secret")
232
    .keystoreType("JKS");
233

234
// Performance optimized server
235
WireMockConfiguration perfConfig = wireMockConfig()
236
    .port(8089)
237
    .containerThreads(50)
238
    .asynchronousResponseEnabled(true)
239
    .asynchronousResponseThreads(10)
240
    .maxHttpClientConnections(100)
241
    .jettyAcceptors(4)
242
    .jettyAcceptQueueSize(500);
243

244
// File-based configuration
245
WireMockConfiguration fileConfig = wireMockConfig()
246
    .port(8089)
247
    .usingFilesUnderDirectory("/path/to/wiremock")
248
    .filenameTemplate("{{request.url}}-{{request.method}}");
249
```
250

251
### Options Interface
252

253
Core configuration interface implemented by WireMockConfiguration with all available options.
254

255
```java { .api }
256
/**
257
 * Main configuration interface with all WireMock options
258
 */
259
interface Options {
260
    // Constants
261
    int DEFAULT_PORT = 8080;
262
    int DYNAMIC_PORT = 0;
263
    int DEFAULT_TIMEOUT = 300_000;
264
    int DEFAULT_CONTAINER_THREADS = 25;
265
    String DEFAULT_BIND_ADDRESS = "0.0.0.0";
266
    
267
    // Core Configuration
268
    int portNumber();
269
    String bindAddress();
270
    int containerThreads();
271
    long timeout();
272
    
273
    // Protocol Configuration
274
    boolean getHttpDisabled();
275
    boolean getHttp2PlainDisabled();
276
    boolean getHttp2TlsDisabled();
277
    HttpsSettings httpsSettings();
278
    JettySettings jettySettings();
279
    
280
    // Storage and File Configuration
281
    FileSource filesRoot();
282
    MappingsLoader mappingsLoader();
283
    MappingsSaver mappingsSaver();
284
    FilenameMaker getFilenameMaker();
285
    
286
    // Request Journal Configuration
287
    boolean requestJournalDisabled();
288
    Optional<Integer> maxRequestJournalEntries();
289
    List<CaseInsensitiveKey> matchingHeaders();
290
    
291
    // Extension Configuration
292
    ExtensionDeclarations getDeclaredExtensions();
293
    boolean isExtensionScanningEnabled();
294
    
295
    // Factory Configuration
296
    HttpServerFactory httpServerFactory();
297
    HttpClientFactory httpClientFactory();
298
    ThreadPoolFactory threadPoolFactory();
299
    
300
    // Security Configuration
301
    Authenticator getAdminAuthenticator();
302
    boolean getHttpsRequiredForAdminApi();
303
    
304
    // Performance Configuration
305
    AsynchronousResponseSettings getAsynchronousResponseSettings();
306
    ChunkedEncodingPolicy getChunkedEncodingPolicy();
307
    int getMaxHttpClientConnections();
308
    boolean getDisableConnectionReuse();
309
    int getWebhookThreadPoolSize();
310
    
311
    // Response Configuration
312
    boolean getGzipDisabled();
313
    boolean getStubRequestLoggingDisabled();
314
    boolean getStubCorsEnabled();
315
    DataTruncationSettings getDataTruncationSettings();
316
    
317
    // Template Configuration
318
    boolean getResponseTemplatingEnabled();
319
    boolean getResponseTemplatingGlobal();
320
    Long getMaxTemplateCacheEntries();
321
    Set<String> getTemplatePermittedSystemKeys();
322
    boolean getTemplateEscapingDisabled();
323
    
324
    // Notification
325
    Notifier notifier();
326
}
327

328
enum ChunkedEncodingPolicy {
329
    ALWAYS, NEVER, BODY_FILE
330
}
331
```
332

333
### Configuration Support Types
334

335
```java { .api }
336
class HttpsSettings {
337
    String keystorePath();
338
    String keystorePassword();
339
    String keyManagerPassword();
340
    String keystoreType();
341
    String trustStorePath();
342
    String trustStorePassword();
343
    String trustStoreType();
344
    boolean needClientAuth();
345
}
346

347
class JettySettings {
348
    Integer getAcceptors();
349
    Integer getAcceptQueueSize();
350
    Integer getRequestHeaderSize();
351
    Integer getResponseHeaderSize();
352
    Long getStopTimeout();
353
    Long getIdleTimeout();
354
}
355

356
class AsynchronousResponseSettings {
357
    boolean isEnabled();
358
    int getThreads();
359
}
360

361
class DataTruncationSettings {
362
    int getMaxLoggedResponseSize();
363
}
364

365
interface Notifier {
366
    void info(String message);
367
    void error(String message);
368
    void error(String message, Throwable t);
369
}
370

371
interface FileSource {
372
    BinaryFile getBinaryFileNamed(String name);
373
    TextFile getTextFileNamed(String name);
374
    void createIfNecessary();
375
    FileSource child(String subDirectoryName);
376
    String getPath();
377
    List<TextFile> listFilesRecursively();
378
}
379
```