Docker (single-node)

Docker runs one KubeMQ node for development and testing. One container runs the full server: every interface, every connector, the persistent store, and the embedded messaging engine — the same container that runs on Docker or Podman; there is no separate native binary install. This guide hosts the complete, runnable Docker configs; the reference pages show per-setting snippets and link back here.

Install KubeMQ first with Install with kmq or Install with Docker. This page changes the settings of a running server.

Every command on this page recreates the container kubemq on the kubemq-data volume, so your messages stay. Remove the running container first with docker stop kubemq and docker rm kubemq. If kmq created the server, remove it with kmq instead, as Install with kmq shows; from then on you manage the container with Docker commands. If you added a license, run each command from kubemq-private with --env-file kubemq-license.env added, as Install with Docker does: a server whose store already used its evaluation does not start without it. If kmq saved your license, create kubemq-license.env first with the license step of Install with Docker; kmq keeps the key in its own store, not in that file.

The store lives on the kubemq-data volume, mounted at /kubemq/store inside the container. It is the same volume Try KubeMQ creates. Persistence is required for the Events Store and Queues patterns.

Three ways to supply config

Every setting has a documented default, so a server runs with no overrides at all. To change a setting you have three delivery methods, in order of how much you are configuring:

Per-field environment variables

Pass each setting as -e GROUP_FIELD=value. The env var is the config.yaml key snake-cased, dotless, and uppercased — store.maxretention becomes STORE_MAX_RETENTION. This is the lightest method, best for a handful of overrides:

docker run -d \  --pull always \  --platform linux/amd64 \  --name kubemq \  --hostname kubemq \  -p 127.0.0.1:50000:50000 \  -p 127.0.0.1:9090:9090 \  -p 127.0.0.1:8080:8080 \  -p 127.0.0.1:9092:9092 \  -e STORE_ENGINE=next \  -e STORE_NEXT_ACK_POLICY=strict \  -e STORE_STORE_PATH=/kubemq/store \  -e API_BIND_ADDRESS=0.0.0.0 \  -e LOG_LEVEL=1 \  -e STORE_MAX_RETENTION=2880 \  -e CONNECTORSCE_ENABLE=false \  -v kubemq-data:/kubemq/store \  europe-docker.pkg.dev/kubemq/images/kubemq-next:latest

A mounted config.yaml

Once you are setting more than a few fields, keep them in a config.yaml and mount it into the container. The server auto-detects YAML or TOML; point it at the file with the --config flag.

log:
  level: 1
store:
  storepath: ./store
  maxretention: 2880
connectors:
  grpc:
    enable: true
    port: "50000"
  rest:
    enable: true
    port: "9090"
  ce:
    enable: false
api:
  port: "8080"

Mount the file and select it with --config. The flag goes after the image name and after the binary path:

docker run -d \  --pull always \  --platform linux/amd64 \  --name kubemq \  --hostname kubemq \  -p 127.0.0.1:50000:50000 \  -p 127.0.0.1:9090:9090 \  -p 127.0.0.1:8080:8080 \  -p 127.0.0.1:9092:9092 \  -e STORE_ENGINE=next \  -e STORE_NEXT_ACK_POLICY=strict \  -e STORE_STORE_PATH=/kubemq/store \  -e API_BIND_ADDRESS=0.0.0.0 \  -v kubemq-data:/kubemq/store \  -v "$(pwd)/config.yaml:/kubemq/config.yaml:ro" \  europe-docker.pkg.dev/kubemq/images/kubemq-next:latest /kubemq/kubemq-run --config /kubemq/config.yaml

The CONFIG environment variable

When mounting a file is awkward — orchestrators that inject env vars, CI runners, secret managers — supply the whole config inline through the CONFIG environment variable. The server writes the value to a file and loads it, exactly as if you had passed --config:

docker run -d \  --pull always \  --platform linux/amd64 \  --name kubemq \  --hostname kubemq \  -p 127.0.0.1:50000:50000 \  -p 127.0.0.1:9090:9090 \  -p 127.0.0.1:8080:8080 \  -p 127.0.0.1:9092:9092 \  -e STORE_ENGINE=next \  -e STORE_NEXT_ACK_POLICY=strict \  -e STORE_STORE_PATH=/kubemq/store \  -e API_BIND_ADDRESS=0.0.0.0 \  -e CONFIG="$(cat config.yaml)" \  -v kubemq-data:/kubemq/store \  europe-docker.pkg.dev/kubemq/images/kubemq-next:latest

CONFIG also accepts a base64-encoded payload, which avoids newline and quoting issues when the value passes through a secret store or a templating layer:

docker run -d \  --pull always \  --platform linux/amd64 \  --name kubemq \  --hostname kubemq \  -p 127.0.0.1:50000:50000 \  -p 127.0.0.1:9090:9090 \  -p 127.0.0.1:8080:8080 \  -p 127.0.0.1:9092:9092 \  -e STORE_ENGINE=next \  -e STORE_NEXT_ACK_POLICY=strict \  -e STORE_STORE_PATH=/kubemq/store \  -e API_BIND_ADDRESS=0.0.0.0 \  -e CONFIG="$(base64 < config.yaml)" \  -v kubemq-data:/kubemq/store \  europe-docker.pkg.dev/kubemq/images/kubemq-next:latest

docker-compose

To run the same single server with Docker Compose, download the Compose file from Install with Docker, then add a docker-compose.override.yml next to it. Compose merges the override automatically, so the downloaded file stays as published, with its kubemq-data volume.

services:
  kubemq:
    command: ["/kubemq/kubemq-run", "--config", "/kubemq/config.yaml"]
    environment:
      LOG_LEVEL: "1"
    volumes:
      - ./config.yaml:/kubemq/config.yaml:ro

Check the merge:

docker compose config

You should see, under kubemq: a command list ending in --config and /kubemq/config.yaml, LOG_LEVEL: "1" next to the published file's variables, and two mounts, the kubemq-data volume at /kubemq/store and config.yaml at /kubemq/config.yaml.

If you added a license, now add env_file: [./kubemq-license.env] under kubemq: in the override, and keep the Compose file and the override in kubemq-private, next to kubemq-license.env; run the next commands there. Add it after the check above, because docker compose config prints the values of an environment file. Leave the line out if you have no license: Compose stops when the file is missing. With a license but without the line, a server whose store already used its evaluation does not start.

Get the latest image:

docker compose pull

You should see kubemq reported as pulled.

Start it:

docker compose up -d

You should see the container kubemq created or recreated, then started. docker compose ps shows it Up.

To supply the config inline instead of mounting a file, drop command and the config.yaml mount from the override and set CONFIG (or CONFIG as base64) under environment.

Configure by domain

Every setting in the configs above is documented in the reference, grouped by domain. Each page lists the config.yaml key, the environment variable, the type, the default, and the valid values.

Verify

Confirm the node is up. Open the dashboard at http://localhost:8080, then check the container logs:

docker logs kubemq

A healthy start logs each interface binding to its port. The health and readiness probes on the API port confirm the server is accepting traffic:

curl http://localhost:8080/health
curl http://localhost:8080/ready

Related

• Install with Docker — install a licensed single server, with Docker or Docker Compose.
• Kubernetes (Helm) — the production target with replicas and Service exposure.
• Configuration overview — the two targets and the config model.
• Configuration reference — every setting, grouped by domain.