Pricing Try it now
PE ST-RMQTT
Community Edition Professional Edition Cloud SENTIENT Edge PE SENTIENT Edge SENTIENT IoT Gateway License Server SENTIENT ANALYTICS Mobile Application PE Mobile Application ST-RMQTT PE ST-RMQTT
Installation > Cluster using Docker Compose
Getting Started Documentation
Architecture API FAQ
On this page

Deploy ST-RMQTT PE Cluster using Docker Compose

This guide will help you set up ST-RMQTT PE in cluster mode using Docker Compose.

Prerequisites

doc warn icon

Don’t forget to add your linux user to the docker group. See Manage Docker as a non-root user.

Pull ST-RMQTT PE Image

Make sure you have logged in to docker hub using the command line.

1
2

docker pull sentient/st-rmqtt-pe-node:2.2.0PE
docker pull sentient/st-rmqtt-pe-integration-executor:2.2.0PE

Clone ST-RMQTT PE Docker Compose repository

1
2

git clone -b release-2.2.0 https://github.com/sentient/st-rmqtt-pe-docker-compose.git
cd st-rmqtt-pe-docker-compose/cluster

Get the license key

Before proceeding, make sure you’ve selected your subscription plan or chosen to purchase a perpetual license. If you haven’t done this yet, please visit the Pricing page to compare available options and obtain your license key.

Note: Throughout this guide, we’ll refer to your license key as YOUR_LICENSE_KEY_HERE.

Configure the license key

1

nano st-rmqtt.env

and put the license secret parameter instead of “YOUR_LICENSE_KEY_HERE”:

1
2

# License info
ST-RMQTT_LICENSE_SECRET=YOUR_LICENSE_KEY_HERE

Installation

Execute the following command to create the necessary volumes for all the services and to update the haproxy config in the created volume.

1

./scripts/docker-create-volumes.sh

Execute the following command to run the installation:

1

./scripts/docker-install-st-rmqtt.sh

Running

Execute the following command to start services:

1

./scripts/docker-start-services.sh

After a while when all services will be successfully started you can make requests to http://{your-host-ip} in you browser (e.g. http://localhost) and connect clients using MQTT protocol on 1883 port.

You should see ST-RMQTT login page. Use the following default credentials for System Administrator:

Username:

1

sysadmin@sentient.org

Password:

1

sysadmin

On the first user log-in you will be asked to change the default password to the preferred one and then re-login using the new credentials.

Logs, stop and start commands

In case of any issues, you can examine service logs for errors. For example, to see ST-RMQTT logs, execute the following command:

1

docker compose logs -f st-rmqtt1

Or use the following command to see the state of all the containers.

1

docker compose ps

Use the next command to inspect the logs of all running services.

1

docker compose logs -f

See docker compose logs command reference for more details.

Execute the following command to stop services:

1

./scripts/docker-stop-services.sh

Execute the following command to stop and completely remove deployed docker containers:

1

./scripts/docker-remove-services.sh

In case you want to remove docker volumes for all the containers, execute the following command. Note: it will remove all your data, so be careful before executing it.

1

./scripts/docker-remove-volumes.sh

It could be useful to update logs (enable DEBUG/TRACE logs) in runtime or change ST-RMQTT or Haproxy configs. In order to do this, you need to make changes, for example, to the haproxy.cfg or logback.xml file. Afterward, execute the next command to apply the changes for the container:

1

./scripts/docker-refresh-config.sh

To reload HAProxy’s configuration without restarting the Docker container, you can send the HUP signal to this process (PID 1):

1

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

Upgrading

Review the release notes and upgrade instruction for detailed information on the latest changes.

If the documentation does not cover the specific upgrade instructions for your case, please contact us so we can provide further guidance.

Backup and restore (Optional)

While backing up your PostgreSQL database is highly recommended, it is optional before proceeding with the upgrade. For further guidance, follow the next instructions.

Upgrade from ST-RMQTT CE to ST-RMQTT PE (v2.2.0)

To upgrade your existing ST-RMQTT Community Edition (CE) to ST-RMQTT Professional Edition (PE), ensure you are running the latest ST-RMQTT CE 2.2.0 version before starting the process. Merge your current configuration with the latest ST-RMQTT PE Docker Compose scripts. Do not forget to configure the license key.

Run the following commands, including the upgrade script to migrate PostgreSQL database data from CE to PE:

1
2
3

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

Generate certificate for HTTPS

We are using HAproxy for proxying traffic to containers and for web UI. By default, we are using 80 and 443 ports. For using HTTPS with a valid certificate, execute these commands:

1
2

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

Note: Valid certificate is used only when you visit web UI by domain in URL.

Enable MQTTS (MQTT over SSL/TLS)

MQTTS allows clients to connect to ST-RMQTT over an encrypted TLS/SSL channel, ensuring the confidentiality and integrity of MQTT messages in transit. There are two common deployment options:

  • Two-way MQTTS (Mutual TLS) – ST-RMQTT terminates TLS, and clients must present valid certificates for authentication.
  • One-way MQTTS (TLS termination at Load Balancer) – HAProxy or another load balancer handles TLS termination, and forwards plain MQTT traffic to ST-RMQTT over a trusted internal network.

Both approaches protect external connections with encryption, but two-way MQTTS adds client certificate verification for higher security, while one-way MQTTS simplifies broker configuration and can reuse existing HTTPS certificates on the load balancer.

Two-way MQTTS

In this configuration, ST-RMQTT itself handles TLS termination and (optionally) client certificate authentication. 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.

To enable MQTT over SSL (MQTTS), you need to provide valid SSL certificates and configure ST-RMQTT to use them.

For more information on supported certificate formats and options, refer to the MQTT over SSL documentation.

Provide SSL Certificates

Obtain a valid SSL certificate and private key. For example:

  • mqttserver.pem – your public certificate (may include full chain);
  • mqttserver_key.pem – your private key.

Self-signed certificates are supported for testing, but we recommend using certificates from a trusted Certificate Authority for production environments.

Mount Certificates into Containers

Open your docker-compose.yml file and uncomment the volume line that mounts the certificate files:

1
2

volumes:
  - PATH_TO_CERTS:/config/certificates

Replace PATH_TO_CERTS with the path to the folder containing your certificate files. Make sure ST-RMQTT can access those file.

Configure Environment Variables

Edit the st-rmqtt.env file and uncomment/configure the following lines to enable SSL:

1
2
3
4

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

Adjust the file paths and password as needed. If your private key is not password-protected, you can leave LISTENER_SSL_PEM_KEY_PASSWORD empty.

Restart Services

Apply the changes by restarting ST-RMQTT services:

1

./scripts/docker-start-services.sh

Once started, your MQTT clients will be able to securely connect to port 8883 using TLS/SSL.

One-way MQTTS

In this setup, TLS is terminated at the load balancer (HAProxy). Clients connect securely to HAProxy over MQTTS (port 8883), and HAProxy forwards plain MQTT (unencrypted) to ST-RMQTT over the internal network (port 1883). You can reuse the same certificate you already use for HTTPS.

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

1
2
3
4
5
6
7
8
9
10

 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 stRmqtt1 st-rmqtt1:1883 check inter 5s resolvers docker_resolver resolve-prefer ipv4
  server stRmqtt2 st-rmqtt2:1883 check inter 5s resolvers docker_resolver resolve-prefer ipv4

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

Next steps