Docker Compose

This guide covers setting up TBMQ in cluster mode using Docker Compose.

• Docker installed.

git clone -b release-2.3.0 https://github.com/thingsboard/tbmq-pe-docker-compose.git
cd tbmq-pe-docker-compose/cluster

Before proceeding, ensure you have an active TBMQ license. If you don't have one yet, visit the Pricing page, choose a pay-as-you-go subscription or a perpetual license, and use the calculator to size your deployment — session and throughput limits, production and development instances, and any add-ons — to obtain your license key.

Open the tbmq.env file:

nano tbmq.env

Find TBMQ_LICENSE_SECRET and replace YOUR_LICENSE_KEY_HERE with your actual license key:

# License info
TBMQ_LICENSE_SECRET=YOUR_LICENSE_KEY_HERE

Create the necessary Docker volumes and update the HAProxy config in the created volume:

./scripts/docker-create-volumes.sh

Run the installation:

./scripts/docker-install-tbmq.sh

Start all services:

./scripts/docker-start-services.sh

Once all services have started, open http://{your-host-ip} in your browser (e.g. http://localhost) and connect MQTT clients on port 1883.

You should see the TBMQ login page. Use the default System Administrator credentials:

Username:

[email protected]

Password:

sysadmin

On first login, you are prompted to change the default password and re-login with the new credentials.

To view TBMQ node logs:

docker compose logs -f tbmq1

To view the state of all containers:

docker compose ps

To inspect logs of all running services:

docker compose logs -f

See the docker compose logs reference for more details.

To stop services:

./scripts/docker-stop-services.sh

To stop and completely remove deployed containers:

./scripts/docker-remove-services.sh

To remove Docker volumes for all containers (warning: deletes all data):

./scripts/docker-remove-volumes.sh

To apply config changes at runtime (e.g. edits to haproxy.cfg or logback.xml):

./scripts/docker-refresh-config.sh

To reload HAProxy configuration without restarting the container, send a HUP signal:

docker exec -it haproxy-certbot sh -c "kill -HUP 1"

1. Check the version-specific notes below for any preparation your target version requires.
2. Back up your database (optional but recommended).
3. Run the upgrade commands.

For full version history and supported upgrade paths, see the upgrade instructions page. If the documentation does not cover your specific upgrade path, contact us for guidance.

If there are no version-specific notes for your upgrade path, skip directly to Run upgrade.

Backing up your PostgreSQL database before upgrading is highly recommended but optional. For guidance, follow the backup and restore instructions.

This is a standard upgrade from v2.2.0. No third-party component changes are required — the official images are already in use since v2.2.0.

Proceed with the upgrade.

CE-to-PE migration is supported for the same version only. If you are on an earlier CE version, upgrade TBMQ CE to the latest version first. For all supported paths, see the upgrade instructions.

Before upgrading, merge your current configuration with the latest TBMQ PE Docker Compose scripts. Update your tbmq.env to include the PE-specific environment variables:

• TBMQ_LICENSE_SECRET — your license key from the license step;
• TBMQ_LICENSE_INSTANCE_DATA_FILE — path to the auto-generated instance data file.

Then run the following commands to stop services, migrate the database, and restart:

./scripts/docker-stop-services.sh
./scripts/docker-upgrade-tbmq.sh --fromVersion=ce
./scripts/docker-start-services.sh

Pull the latest changes from the release branch:

git pull origin release-2.3.0

Note: Make sure any custom changes are not lost during the merge. Also ensure TBMQ_VERSION in the .env file is set to the target version (e.g. 2.3.0 for the latest).

After pulling, execute the upgrade commands:

./scripts/docker-stop-services.sh
./scripts/docker-upgrade-tbmq.sh
./scripts/docker-start-services.sh

HAProxy handles traffic proxying and serves the web UI on ports 80 and 443 by default. To enable HTTPS with a valid certificate, run:

docker exec haproxy-certbot certbot-certonly --domain your_domain --email your_email
docker exec haproxy-certbot haproxy-refresh

MQTTS allows clients to connect over an encrypted TLS/SSL channel. There are two common approaches:

• Two-way MQTTS (Mutual TLS) — TBMQ terminates TLS; clients must present valid certificates.
• One-way MQTTS (TLS termination at load balancer) — HAProxy handles TLS termination and forwards plain MQTT to TBMQ over the internal network.

Both approaches encrypt external connections. Two-way MQTTS adds client certificate verification for higher security; one-way MQTTS simplifies broker configuration and can reuse existing HTTPS certificates.

In this configuration, TBMQ handles TLS termination and (optionally) client certificate authentication directly. This approach is suitable when you want the broker to fully control SSL/TLS and mutual authentication without relying on a load balancer for security.

For supported certificate formats and options, see the MQTT over SSL guide.

Provide SSL certificates

Obtain a valid SSL certificate and private key:

• mqttserver.pem — public certificate (may include the full chain)
• mqttserver_key.pem — private key

Mount certificates into the container

In docker-compose.yml, uncomment and update the volume mount:

volumes:
  - PATH_TO_CERTS:/config/certificates

Replace PATH_TO_CERTS with the path to your certificate files. Ensure TBMQ has read access.

Configure environment variables

Edit the tbmq.env file and uncomment/configure the following lines:

LISTENER_SSL_ENABLED=true
LISTENER_SSL_PEM_CERT=/config/certificates/mqttserver.pem
LISTENER_SSL_PEM_KEY=/config/certificates/mqttserver_key.pem
LISTENER_SSL_PEM_KEY_PASSWORD=server_key_password

Leave LISTENER_SSL_PEM_KEY_PASSWORD empty if your private key has no password.

Restart services

./scripts/docker-start-services.sh

Once restarted, MQTT clients can connect securely on port 8883.

TLS is terminated at HAProxy. Clients connect to HAProxy on port 8883, which forwards plain MQTT to TBMQ on port 1883. You can reuse the same certificate used for HTTPS.

Point HAProxy to your certificate bundle (PEM with full chain + private key). If you reuse the HTTPS certificate, reference the same bundle. Update the haproxy.cfg file:

 listen mqtts-in
  bind *:${MQTTS_PORT} ssl crt /usr/local/etc/haproxy/certs.d/fullchain-and-key.pem
  mode tcp
  option clitcpka # For TCP keep-alive
  timeout client 3h
  timeout server 3h
  option tcplog
  balance leastconn
  server tbMqtt1 tbmq1:1883 check inter 5s resolvers docker_resolver resolve-prefer ipv4
  server tbMqtt2 tbmq2:1883 check inter 5s resolvers docker_resolver resolve-prefer ipv4

Replace fullchain-and-key.pem with the actual filename of your certificate bundle.