KubeMQ
Operate

Back up and restore

Back up and restore a KubeMQ Docker server's store volume safely: stop the server, archive with a helper container, restore in place, verify.

This page shows how to back up the store of a KubeMQ server running in Docker and restore it in place. The store holds your messages, accounts, license records and the installation's identity. When you finish, you have an archive, and a restored server shows the same license and messages.

This page covers one Docker server. Kubernetes has no supported backup procedure yet. Scaling a cluster to zero to copy its volumes does not work: the operator never applies a changed server count. Contact support before relying on a restore.

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

  • A KubeMQ server running in Docker as container kubemq on volume kubemq-data, as Try KubeMQ, Install with kmq and Install with Docker start it.
  • kmq, installed as in Try KubeMQ, for kmq license only.
  • A short outage: the server stops while its store is archived, because a running store cannot be copied consistently.
  • Free disk space at least the size of the store.

With Podman: run every command with podman in place of docker.

Create a private folder for the archive and work inside it:

Terminal
mkdir -p -m 700 kubemq-private
Terminal
cd kubemq-private

Steps

Steps 1 to 4 back up the store. Steps 5 to 10 restore it and prove your messages came back. A public Debian container does the archiving, because the KubeMQ image has no archive tools. It keeps each file's owner, user 1001.

Send a check message

Put one message on a new backup-check queue. Step 10 receives it after the restore.

Terminal
curl -s -X POST http://localhost:9090/queue/send \
  -H "Content-Type: application/json" \
  -d '{"Channel":"backup-check","ClientID":"backup-check","BodyString":"backup-check"}'

You should see:

Output
{"is_error":false,"message":"OK","data":{"MessageID":"…","SentAt":…}}

Stop the server

Terminal
docker stop kubemq

You should see:

Output
kubemq

Archive the volume

Terminal
docker run --rm -v kubemq-data:/data:ro -v "$(pwd)":/backup \
  docker.io/library/debian:stable-slim \
  sh -c 'tar --numeric-owner -cpf /backup/kubemq-store.tar -C /data . && tar -tf /backup/kubemq-store.tar | head -n 1'

The output is the first entry of the new kubemq-store.tar. You should see:

Output
./

On a Linux host with SELinux enforcing, add :z to the $(pwd) mount: -v "$(pwd)":/backup:z.

Keep the archive private and encrypted, with a copy away from this machine. It holds the installation's identity and license records.

Start the server again

Terminal
docker start kubemq

You should see:

Output
kubemq

Stop the server before the restore

The restore reuses the same container and volume. Nothing is recreated, so the installation keeps its identity.

Terminal
docker stop kubemq

You should see:

Output
kubemq

Keep a safety archive

Archive the store you are about to replace. If the restore goes wrong, repeat the next step with kubemq-store-before-restore.tar to put it back.

Terminal
docker run --rm -v kubemq-data:/data:ro -v "$(pwd)":/backup \
  docker.io/library/debian:stable-slim \
  sh -c 'tar --numeric-owner -cpf /backup/kubemq-store-before-restore.tar -C /data . && tar -tf /backup/kubemq-store-before-restore.tar | head -n 1'

You should see:

Output
./

Replace the store with the backup

Data loss: this step deletes the current store

Data loss: this command deletes everything in kubemq-data before it unpacks the archive. Run it only after the safety archive succeeded. Never run two servers from copies of the same store: they share one installation identity.

Terminal
docker run --rm -v kubemq-data:/data -v "$(pwd)":/backup:ro \
  docker.io/library/debian:stable-slim \
  sh -c 'find /data -mindepth 1 -delete && tar --numeric-owner -xpf /backup/kubemq-store.tar -C /data && echo restored'

You should see:

Output
restored

Start the server and wait until it is ready

Terminal
docker start kubemq && for i in $(seq 60); do curl -fs -o /dev/null http://localhost:8080/ready && echo ready && break; sleep 2; done

You should see:

Output
kubemq
ready

Check the license

Terminal
kmq license

The license is the one the server had at backup time. You should see:

Output
SERVER  STATE   PLAN   SERVERS LICENSED  EXPIRES  DAYS LEFT  RUNS UNTIL  VERSION  CHECKED  PROBLEM
kubemq  …

Receive the check message

Terminal
curl -s -X POST http://localhost:9090/queue/receive \
  -H "Content-Type: application/json" \
  -d '{"Channel":"backup-check","ClientID":"backup-check","MaxNumberOfMessages":1,"WaitTimeSeconds":5}'

The message from step 1 comes back, with its body base64-encoded. You should see:

Output
{"is_error":false,"message":"OK","data":{…,"Messages":[{"MessageID":"…","ClientID":"backup-check","Channel":"backup-check","Body":"YmFja3VwLWNoZWNr",…}],"MessagesReceived":1}}

If something goes wrong

  • The server does not start, or never becomes ready: check docker logs kubemq.
  • kmq license reports a problem: see Troubleshooting.
  • You cannot sign in to the dashboard: the restore brought back the accounts the store held when you archived it. See Dashboard Access and Recovery.

Next steps

Was this page helpful?

Dashboard Access and Recovery

Create a Docker dashboard administrator, sign in again, and reset a forgotten password without deleting KubeMQ data.

kmq CLI

Drive KubeMQ from the terminal with the kmq command-line client — messaging, observability, contexts, roles, and the installable agent skill.

On this page

Before you startStepsSend a check messageStop the serverArchive the volumeStart the server againStop the server before the restoreKeep a safety archiveReplace the store with the backupStart the server and wait until it is readyCheck the licenseReceive the check messageIf something goes wrongNext steps