Docker (single-node)

Docker single-node is the standalone KubeMQ server, containerized. One container runs the full server: every interface, every connector, the persistent store, and the embedded messaging engine. There is no separate "bare-binary" target — the container is the binary. This guide hosts the complete, runnable Docker configs; the reference pages show per-setting snippets and link back here.

Install KubeMQ first → Docker install. This page covers how to configure a single node, not how to install one.

The store is bind-mounted to /store inside the container — the path the server writes to by default. 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 \  --name kubemq \  -p 50000:50000 \  -p 9090:9090 \  -p 8080:8080 \  -e KUBEMQ_TOKEN=YOUR_LICENSE_KEY \  -e LOG_LEVEL=1 \  -e STORE_MAX_RETENTION=2880 \  -e CONNECTORSCE_ENABLE=false \  -v "$(pwd)/kubemq-store:/store" \  europe-docker.pkg.dev/kubemq/images/kubemq:next

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 (the server's start command takes arguments after the image name):

# Replace with your license key
key: YOUR_LICENSE_KEY
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:

docker run -d \
  --name kubemq \
  -p 50000:50000 \
  -p 9090:9090 \
  -p 8080:8080 \
  -v "$(pwd)/kubemq-store:/store" \
  -v "$(pwd)/config.yaml:/kubemq/config.yaml:ro" \
  europe-docker.pkg.dev/kubemq/images/kubemq:next \
  --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 \
  --name kubemq \
  -p 50000:50000 \
  -p 9090:9090 \
  -p 8080:8080 \
  -v "$(pwd)/kubemq-store:/store" \
  -e CONFIG="$(cat config.yaml)" \
  europe-docker.pkg.dev/kubemq/images/kubemq:next

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 \
  --name kubemq \
  -p 50000:50000 \
  -p 9090:9090 \
  -p 8080:8080 \
  -v "$(pwd)/kubemq-store:/store" \
  -e CONFIG="$(base64 < config.yaml)" \
  europe-docker.pkg.dev/kubemq/images/kubemq:next

docker-compose

The same single node as a docker-compose.yaml, combining a mounted config.yaml with a couple of per-field environment overrides:

services:
  kubemq:
    image: europe-docker.pkg.dev/kubemq/images/kubemq:next
    container_name: kubemq
    command: ["--config", "/kubemq/config.yaml"]
    ports:
      - "50000:50000"  # gRPC
      - "9090:9090"    # REST / WebSocket
      - "8080:8080"    # API / Dashboard
    environment:
      - KUBEMQ_TOKEN=${KUBEMQ_TOKEN:-}
      - LOG_LEVEL=1
    volumes:
      - kubemq-store:/store
      - ./config.yaml:/kubemq/config.yaml:ro
    restart: unless-stopped

volumes:
  kubemq-store:

Start it:

docker compose up -d

To supply the config inline instead of mounting a file, drop the command and config.yaml volume and set CONFIG (or CONFIG as base64) in the environment block.

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

• 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.