Configuration

Runner is configured through environment variables in docker-compose.yml. After any change, restart the stack to apply it:

docker compose up -d

Security

The default compose file ships with placeholder values that are fine for a local evaluation. Change these before exposing Runner to a network.

MongoDB password

The password must be set in two places and must match:

# MongoDB service
MONGO_INITDB_ROOT_PASSWORD: your-db-password

# API service — same password in the connection string
DB_URL: mongodb://root:your-db-password@mongodb/nodepit-runner?authSource=admin

WARNING

MONGO_INITDB_ROOT_PASSWORD is only read when MongoDB initialises a new database. Changing it after first run has no effect. To rotate the password on a running installation, use mongosh and db.changeUserPassword(), then update DB_URL to match.

API key

A shared secret between the API and Executor services. Set the same value in both:

# API service
API_KEY: your-api-key

# Executor service
API_KEY: your-api-key

Deployment

Public URL

Set WEB_BASE_URL to the hostname or IP address your users will access Runner at. The API uses this to generate links in notification emails and other outbound content — if it's wrong, those links will be broken.

# API service
WEB_BASE_URL: https://runner.example.com

Worker resources

Each executor spawns a Docker container per workflow run. Without limits, a runaway workflow can starve the host. Set CPU and memory limits to contain the blast radius:

# Executor service
DOCKER_CPU_PERIOD: 100000
DOCKER_CPU_QUOTA: 85000 # 85% of one CPU
DOCKER_MEMORY: 1500000000 # 1.5 GB

See the Docker documentation for details on these values.

To mount additional host paths into worker containers, use DOCKER_BINDS:

DOCKER_BINDS: /data/shared:/data/shared,/certs:/certs:ro

Private registry

Each executor builds and caches Docker images locally. When running multiple executors, each one rebuilds its own cache independently — wasting time and disk space.

A shared private registry solves this: images are pushed after the first build and pulled by all other executors instead of being rebuilt.

# Executor service
DOCKER_REGISTRY_URL: registry.example.com
DOCKER_REGISTRY_USER: your-registry-user
DOCKER_REGISTRY_PASSWORD: your-registry-password

When a registry is configured, built images are automatically removed from the executor after being pushed. Set DOCKER_REMOVE_IMAGES: false to keep a local copy as well.

Executor identity

Each executor registers itself with the API on startup. You can give it a display name and tags that appear in the Executors list and can be used to route specific projects to specific executors:

# Executor service
INITIAL_DESCRIPTION: Production executor
INITIAL_TAGS: prod,eu-west

See Executors for how to use tags for routing.

Environment variables reference

API

Variable	Required	Default	Description
API_KEY	yes	—	Secret token that authorises Executor connections to the API. Must match the API_KEY set on each Executor.
DB_URL	yes	—	MongoDB connection string in the format mongodb://user:password@host/database?authSource=admin.
WEB_BASE_URL	yes	—	Publicly reachable URL of the web UI. Used to build absolute links in notification emails and other outbound content.

Executor

Variable	Required	Default	Description
API_BASE_URL	yes	—	Base URL of the API service as reachable from the Executor container, e.g. http://api:3000.
API_KEY	yes	—	Secret token used to authenticate with the API. Must match the API_KEY set on the API.
DOCKER_BINDS	no	—	Comma-separated volume mounts added to every worker container, in host:container[:options] format. Useful for sharing certificates, SSH keys, or data directories.
DOCKER_CPU_PERIOD	no	100000	CPU scheduling period in microseconds. Used together with DOCKER_CPU_QUOTA to set a CPU limit: quota ÷ period = fraction of a CPU allocated per worker container.
DOCKER_CPU_QUOTA	no	—	Microseconds of CPU time allocated per period. Set to 85000 with the default period to allow up to 85% of one CPU per worker container.
DOCKER_MEMORY	no	—	Hard memory limit for worker containers in bytes. Containers that exceed this limit are killed.
DOCKER_NETWORK_MODE	no	bridge	Docker network mode for worker containers. Accepts any value supported by Docker: bridge, host, none, or a named network.
DOCKER_REGISTRY_PASSWORD	no	—	Password for authenticating with the registry configured in DOCKER_REGISTRY_URL.
DOCKER_REGISTRY_URL	no	—	URL of a private Docker registry. When set, built images are pushed here so other Executor instances can pull them instead of rebuilding.
DOCKER_REGISTRY_USER	no	—	Username for authenticating with the registry configured in DOCKER_REGISTRY_URL.
DOCKER_REMOVE_IMAGES	no	true when registry is set	When true, images are deleted from the local Executor after being pushed to the registry, freeing disk space. Has no effect when no registry is configured.
INITIAL_DESCRIPTION	no	—	Human-readable name for this Executor instance, shown in the Executors list in the UI. Useful when running multiple Executors.
INITIAL_TAGS	no	—	Comma-separated tags assigned to this Executor on startup. Tags are used to route projects to specific Executors.

MongoDB

Variable	Required	Default	Description
MONGO_INITDB_ROOT_PASSWORD	yes	—	Password for the MongoDB root user. Only applied when the database is initialised for the first time — changing it later has no effect on an existing database.
MONGO_INITDB_ROOT_USERNAME	yes	—	Username for the MongoDB root user. Only applied on first initialisation.