Environment variables

The following environment variables are supported:

Variable name	Purpose	Default	Description/example(s)
IMPOSTER_ADD_ENGINE_RESPONSE_HEADERS	Add response headers for server and unique request ID.	true	false
IMPOSTER_AUTO_BASE_PATH	Automatically set the base path for each configuration file, based on its relative path from the configuration root directory.	false	true
IMPOSTER_CACHE_DIR	Path to a directory in which to store cached data, such as remote specifications.	<Java temporary directory>/imposter-cache	/path/to/dir
IMPOSTER_CONFIG_DIR	The path to the configuration directory. Can be specified as a comma-separated list. See configuration location.	Empty	/path/to/config/dir - See Configuration Location.
IMPOSTER_CONFIG_SCAN_RECURSIVE	Scan for configuration files recursively within the configuration directories. See recursive configuration discovery.	false	true
IMPOSTER_CONFIG_DISCOVER_ENVFILES	Discover envfiles. See below.	true	false
IMPOSTER_ESCAPE_COLONS_IN_PATH	Escape colons in paths.	false	true
IMPOSTER_EXTERNAL_PLUGINS	Enable loading of external (out-of-process) plugins from the plugin directory. Requires Imposter 5.	false	true
IMPOSTER_FEATURES	Enables or disables features. See Features documentation.	Per default features.	metrics=false,stores=true
IMPOSTER_HTTP2_ENABLED	Enable or disable HTTP/2 protocol support. Both TLS cert and key must be configured for TLS. Requires Imposter 5.	true	false
IMPOSTER_IGNORE_CONFIG_ERRORS	Log errors encountered during configuration parsing or plugin configuration instead of throwing an exception. Defaults to false, as skipping a configuration might also skip the security conditions it contains.	false	boolean
IMPOSTER_JS_PLUGIN	Sets the JavaScript implementation.	js-graal	Can be changed to js-nashorn plugin, if installed.
IMPOSTER_LOG_LEVEL	Sets logging level.	DEBUG	INFO, DEBUG, TRACE
IMPOSTER_LOG_REQUEST_BODY	Include request in structured log entries.	false	true - See Metrics, logs and telemetry.
IMPOSTER_LOG_REQUEST_HEADERS	Comma separated list of request headers to add to structured log entries.	Empty	X-Correlation-ID,User-Agent - See Metrics, logs and telemetry.
IMPOSTER_LOG_RESPONSE_BODY	Include response in structured log entries.	false	true - See Metrics, logs and telemetry.
IMPOSTER_LOG_RESPONSE_HEADERS	Comma separated list of response headers to add to structured log entries.	Empty	Server,Content-Type - See Metrics, logs and telemetry.
IMPOSTER_LOG_SUMMARY	Log a JSON formatted summary message on each request.	false	true
IMPOSTER_LOG_SUMMARY_PRETTY	Pretty print the summary log JSON.	false	true
IMPOSTER_NORMALISE_HEADER_KEYS	Forces header keys to be lowercased.	true	boolean
IMPOSTER_OPENAPI_ALLOW_FILE_REFS	Allow OpenAPI $ref to resolve local file references. Requires Imposter 5.	true	false
IMPOSTER_OPENAPI_ALLOW_REMOTE_REFS	Allow OpenAPI $ref to resolve remote (http/https) references. Requires Imposter 5.	false	true
IMPOSTER_OPENAPI_EXPOSE_SPEC	Expose the OpenAPI specification and UI. See OpenAPI plugin.	true	false
IMPOSTER_OPENAPI_REMOTE_FILE_CACHE	Locally cache remote OpenAPI specifications. See OpenAPI plugin.	false	true
IMPOSTER_OPENAPI_SPEC_PATH_PREFIX	Overrides the default specification path prefix. See OpenAPI plugin.	/_spec	/openapi-spec
IMPOSTER_OPENAPI_VALIDATION_DEFAULT_BEHAVIOUR	The default behaviour for OpenAPI validation issues. See OpenAPI validation.	IGNORE	See OpenAPI validation.
IMPOSTER_PASSTHROUGH_FORWARDED_HEADERS	When true, injects X-Forwarded-* and Via headers on requests forwarded to an upstream. See Upstream services.	false	true
IMPOSTER_PASSTHROUGH_TIMEOUT	Timeout for requests forwarded to an upstream (Go duration syntax). See Upstream services.	30s	5s, 1m
IMPOSTER_PLUGIN_ARGS	Comma separated map of plugin arguments. Analogous to --pluginArg command line argument.	Empty	openapi.scheme=https,openapi.title=Mocks
IMPOSTER_PLUGIN_CLASSLOADER_STRATEGY	Sets the classloader strategy for plugins.	Parent-first	child
IMPOSTER_PLUGIN_DIR	Path to a directory containing additional plugin JAR files.	Empty	Used by Stores and Plugins.
IMPOSTER_PORT	The port on which the HTTP server listens. Requires Imposter 5.	8080	3000
IMPOSTER_PREFER_EXACT_MATCH_ROUTES	Prefer routes with exact matches over those with path placeholders when matching requests.	true	boolean
IMPOSTER_RATE_LIMITER_TTL	TTL in seconds for rate limiter data. Requires Imposter 5.	300	600
IMPOSTER_STORE_DRIVER	Sets the store driver plugin.	store-inmem	See Stores.
IMPOSTER_STORE_DYNAMODB_ENDPOINT	Custom DynamoDB API endpoint. Requires Imposter 4.	None (uses AWS default)	http://localhost:4566
IMPOSTER_STORE_DYNAMODB_OBJECT_SERIALISATION	How to serialise objects in DynamoDB; allowed values are BINARY or MAP. Requires Imposter 4.	BINARY	MAP
IMPOSTER_STORE_DYNAMODB_REGION	AWS region for the DynamoDB store driver. Falls back to AWS_REGION.	Value of AWS_REGION	us-east-1
IMPOSTER_STORE_DYNAMODB_TABLE	DynamoDB table name for the DynamoDB store driver.	Imposter (4.x) / Empty, required (5.x)	imposter-store
IMPOSTER_STORE_DYNAMODB_TTL	TTL in seconds for DynamoDB store items.	No TTL	3600
IMPOSTER_STORE_DYNAMODB_TTL_ATTRIBUTE	Name of the DynamoDB TTL attribute.	ttl	expiresAt
IMPOSTER_STORE_INMEMORY_TTL	TTL in seconds for in-memory store entries. Requires Imposter 5.	No TTL	600
IMPOSTER_STORE_KEY_PREFIX	Sets a prefix for store keys.	Empty	See Stores.
IMPOSTER_STORE_REDIS_EXPIRY	Expiration duration for Redis store keys. In Imposter 4, value is in seconds (default: 1800). In Imposter 5, value uses Go duration syntax (default: no expiration).	1800 (4.x) / No expiration (5.x)	60, 30m
IMPOSTER_SUPPORT_LEGACY_CONFIG	Enable support for legacy (pre-current) config file format with on-the-fly transformation. Requires Imposter 5.	false	true
IMPOSTER_SCRIPT_CACHE_ENTRIES	The number of precompiled scripts to cache. Precompiled scripts execute faster, but the cache uses memory.	20	30
IMPOSTER_SCRIPT_PRECOMPILE	Precompile scripts at startup.	true	boolean
IMPOSTER_SERVER_URL	Override the server base URL. If unset, derived from the port and TLS configuration. Requires Imposter 5.	http://localhost:8080	https://mock.example.com
IMPOSTER_TLS_CERT_FILE	Path to a PEM-encoded TLS certificate file. Both cert and key must be set for TLS. Requires Imposter 5.	Empty	/path/to/cert.pem
IMPOSTER_TLS_KEY_FILE	Path to a PEM-encoded TLS private key file. Both cert and key must be set for TLS. Requires Imposter 5.	Empty	/path/to/key.pem
IMPOSTER_WSDL_SPEC_PATH_PREFIX	Overrides the default WSDL web UI path prefix. Requires Imposter 5.	/_wsdl	/wsdl-ui
IMPOSTER_RESPONSE_FILE_CACHE_ENTRIES	The number of response files to cache in memory. Cached response files don't require disk I/O, but the cache uses memory.	20	30
IMPOSTER_YAML_CODE_POINT_LIMIT	The maximum number of characters to parse in a YAML file. The default is 3MB. Note that the size depends on the file encoding.	3145728 (3MB)	10485760 (10MB)

Note: other features may include their own environment variables. See the feature specific documentation for more details.

Setting environment variables using a file

You can use an environment file ('envfile') to pass environment variables to Imposter. To do this, add a file named .env adjacent to your configuration files, for example:

$ ls
.env
imposter-config.yaml

$ cat .env
IMPOSTER_LOG_LEVEL=info
OTHER_ENV_VAR=example

Referencing environment variables in configuration files

In addition to the IMPOSTER_* variables above, you can reference any environment variable from within a plugin configuration file using ${env.NAME} syntax. This is useful for injecting hostnames, paths, secrets, or other values without hard-coding them.

plugin: rest
resources:
  - path: /example
    response:
      content: "${env.EXAMPLE_RESPONSE}"

A default can be provided with ${env.NAME:-defaultValue}, which is used when the variable is empty or unset.

For full details — including default values and the related ${var.NAME} syntax for configuration variables — see Configuration.