Install with Docker

This page turns the server you started in Try KubeMQ into a licensed server you keep, using your own container commands. When you finish, kmq license reports that license adoption is accepted and durable and your data is unchanged. Time: about 10 minutes.

With Podman, use podman in place of docker in every command.

These commands are for bash on macOS and Linux. On Windows, run them in WSL (Windows Subsystem for Linux), or use the kmq tab of Try KubeMQ, which runs natively on Windows.

Before you start

Create a private folder, readable only by you, and work inside it:

mkdir -p -m 700 kubemq-private

cd kubemq-private

• A server from Try KubeMQ, Docker tab. After the kmq tab, use Install with kmq. No server? See If something goes wrong.
• kmq, the KubeMQ command-line tool, installed as in Try KubeMQ.
• A trial key or a license key: see Plans compared.

Steps

chmod 600 license.key

(umask 077; { printf 'KUBEMQ_LICENSE_KEY='; cat license.key; } > kubemq-license.env)

docker stop kubemq

docker rm kubemq

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 \  --env-file kubemq-license.env \  -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 \  europe-docker.pkg.dev/kubemq/images/kubemq-next:latest

podman 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 \  --env-file kubemq-license.env \  -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 \  europe-docker.pkg.dev/kubemq/images/kubemq-next:latest

docker ps --filter name=kubemq --format '{{.Names}}: {{.Status}}'

HARNESS_OUTPUT_PENDING

kmq auth login --api-address http://127.0.0.1:8080 --context-name kubemq --username admin

kmq context use kubemq

kmq license

{
  "server_version": "...",
  "adoption": {
    "configured_input_sha256": "...",
    "accepted_input_sha256": "...",
    "state": "accepted",
    "durable": true
  },
  "plan": "trial",
  "mode": "online",
  "source": "key",
  "license_expires_at": "...",
  "lease_expires_at": "...",
  "run_until": "...",
  "over_cap": false,
  "stop_cause": null
}

Use Docker Compose instead

Instead of step 1's start command, use Compose:

curl -fsSLO https://docs.kubemq.io/docker-compose.yml

Turn on its env_file line:

sed -i.bak 's|# env_file:|env_file:|' docker-compose.yml

Then:

docker compose pull

docker compose up -d

Compose reuses kubemq-data; expect a warning that Compose did not create it. Check it:

docker compose ps

You should see:

HARNESS_OUTPUT_PENDING

Then step 2.

Replace the license later

Run mv license.key license.key.old, save the new key, and repeat step 1 from the environment file on (with Compose, after the environment file, run docker compose up -d --force-recreate), then step 2. If the server does not start, restore the old key the same way; see Troubleshooting.

Remove the server

docker stop kubemq and docker rm kubemq, or docker compose down, keep the kubemq-data volume. Never run docker compose down -v.

docker volume rm kubemq-data

If something goes wrong

• Start with a trial key or license key. Do step 1 without stopping or removing a container, then step 2, then create the administrator at http://localhost:8080.
• A port is in use. Change the host side of its -p flag, such as -p 127.0.0.1:18080:8080. For 8080, also run kmq license --endpoint http://127.0.0.1:18080.
• The container stops at start. docker logs kubemq ends with a Troubleshooting link, for example #first-boot-bad-key (key refused) or #no-license-input (license env file missing).
• Compose keeps restarting it after a licensing stop. Run docker compose stop, fix the license, then docker compose up -d.

Next steps