# Install with Docker (/deploy/install/docker)
This page turns the server you started in [Try KubeMQ](/deploy/quickstart) into a licensed server you keep, using your own container commands. When you finish, `kmq license` reports an active license 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](/deploy/quickstart), which runs natively on Windows.
## Before you start [#before-you-start]
Create a private folder, readable only by you, and work inside it:
```bash
mkdir -p -m 700 kubemq-private
```
```bash
cd kubemq-private
```
* A server from [Try KubeMQ](/deploy/quickstart), Docker tab. After the kmq tab, use [Install with kmq](/deploy/install/kmq). No server? See [If something goes wrong](#if-something-goes-wrong).
* kmq, the KubeMQ command-line tool, installed as in [Try KubeMQ](/deploy/quickstart#install-kmq).
* A trial key or a license key: see [Plans compared](/licensing#compare-the-options).
## Steps [#steps]
### Add your license [#add-your-license]
1. Open the [trial page](https://onboarding.kubemq.io/trial).
2. Choose **Docker (1 server)**.
3. Enter your work email, name and company; accept the trial terms .
4. Enter the code KubeMQ emails you. The trial key arrives by email.
No email? Use **Recover a trial key** on the same page.
Or use the kmq trial steps on [Install with kmq](/deploy/install/kmq#add-your-license) with `--platform docker`, then run `kmq license export --credential YOUR_LICENSE_REF --out license.key` instead of saving the key below. Replace: `YOUR_LICENSE_REF` — the `credential` value that `kmq trial claim` printed.
Use the key from your KubeMQ order email.
Save the license key as `license.key` in this folder. The file holds only the key, on one line, with no quotes and no `KUBEMQ_LICENSE_KEY=` prefix. Then make it readable by you alone:
```bash
chmod 600 license.key
```
This file is a secret. Do not commit it, paste it into chat, or attach it to a support ticket.
Write the key into a Docker environment file:
```bash
(umask 077; { printf 'KUBEMQ_LICENSE_KEY='; cat license.key; } > kubemq-license.env)
```
Stop and remove the container; `kubemq-data` keeps the data:
```bash
docker stop kubemq
```
```bash
docker rm kubemq
```
Start it again with the license:
With Podman:
Check that the server is running:
```bash
docker ps --filter name=kubemq --format '{{.Names}}: {{.Status}}'
```
You should see:
```text title="Output"
HARNESS_OUTPUT_PENDING
```
| Flag | What it does |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-p 127.0.0.1:…` | Publishes four ports to this machine only: `50000` gRPC, `9090` REST, `8080` dashboard and management API, `9092` Kafka-compatible. |
| `--name kubemq`, `--hostname kubemq` | Name the container and the server. The server files its data under the hostname, so keep both when you recreate the container. |
| `-v kubemq-data:/kubemq/store` | Keeps messages, the administrator, the server's identity and its license in the `kubemq-data` volume. |
| `--env-file kubemq-license.env` | Sets `KUBEMQ_LICENSE_KEY`. Keep it on every start: once the server accepts a key, it refuses to start without one. See [Core & Licensing](/configure/reference/core#license). |
| `-e STORE_ENGINE=next` | Selects the storage engine. |
| `-e STORE_NEXT_ACK_POLICY=strict` | Confirms a message only after it is written to disk. |
| `-e STORE_STORE_PATH=/kubemq/store` | Stores data on the volume. |
| `-e API_BIND_ADDRESS=0.0.0.0` | Lets the published management port reach the server inside the container. |
| `--pull always` | Fetches the latest release on every start. |
| `--restart on-failure:5` | Restarts the server after a failure, at most five times. |
| `--platform linux/amd64` | Runs the x86-64 image; an Arm machine emulates it. |
### Check the license [#check-the-license]
```bash
kmq license
```
You should see:
```text title="Output"
HARNESS_OUTPUT_PENDING
```
`STATE` is `active`, `PLAN` is `trial` or your plan, and `EXPIRES` is the date you expect. Other states: [How licensing works](/licensing/how-it-works#check-license-status). If kmq cannot connect, wait a few seconds and run it again.
Sign in at `http://localhost:8080`: the `orders` channel from Try KubeMQ is still there.
Open the [Release notes](/release-notes) and copy the release number exactly as shown. Wherever a command names `kubemq-next:latest`, write `kubemq-next:YOUR_VERSION` instead, and remove `--pull always` from the `docker run` or `podman run` command.
Replace: `YOUR_VERSION` — the release number you copied, with a leading `v`.
To pin by digest, write `kubemq-next@YOUR_DIGEST` instead, with the server image digest the release notes list.
Replace: `YOUR_DIGEST` — the digest, starting `sha256:`.
Pinned installs do not update themselves. Check the release notes and move to the latest release regularly.
### Use Docker Compose instead [#use-docker-compose-instead]
Instead of step 1's start command, use Compose:
```bash
curl -fsSLO https://docs.kubemq.io/docker-compose.yml
```
Turn on its `env_file` line:
```bash
sed -i.bak 's|# env_file:|env_file:|' docker-compose.yml
```
Then:
```bash
docker compose pull
```
```bash
docker compose up -d
```
Compose reuses `kubemq-data`; expect a warning that Compose did not create it. Check it:
```bash
docker compose ps
```
You should see:
```text title="Output"
HARNESS_OUTPUT_PENDING
```
Then step 2.
Open the [Release notes](/release-notes) and copy the release number exactly as shown. In `docker-compose.yml`, change the `image:` line to `europe-docker.pkg.dev/kubemq/images/kubemq-next:YOUR_VERSION`, keep the file under version control, and run `docker compose up -d`.
Replace: `YOUR_VERSION` — the release number you copied, with a leading `v`.
To pin by digest, write `kubemq-next@YOUR_DIGEST` instead, with the server image digest the release notes list.
Replace: `YOUR_DIGEST` — the digest, starting `sha256:`.
Pinned installs do not update themselves. Check the release notes and move to the latest release regularly.
### Replace the license later [#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](/licensing/troubleshooting#license-not-accepted).
## Remove the server [#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`.
This deletes every message, the administrator and the server's identity.
```bash
docker volume rm kubemq-data
```
## If something goes wrong [#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](/licensing/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 [#next-steps]
## Container command examples
```sh
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
```
```sh
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
```