Back to all

How to Install Pro Mosquitto on Ubuntu Linux Using Docker

In today’s IoT-driven world, reliable and scalable message brokers are central to managing communication between devices and applications. The Pro Mosquitto MQTT broker, an industrial-grade and secure version of the widely adopted Mosquitto broker, offers enhanced features suitable for enterprise-level deployments.

In this guide, I will walk you through installing and running Pro Mosquitto on a Linux system using Docker, ensuring a smooth setup for your messaging needs. By the end of this article, you will have a fully functional Pro Mosquitto MQTT broker running in a Docker container, ready to handle your MQTT messaging efficiently.

Project prerequisites: Configuring Pro Mosquitto on Ubuntu Linux

Before proceeding with the installation, it is crucial to ensure the proper configuration of your system. This guide will demonstrate the installation of the Pro Edition for Eclipse Mosquitto™ on a Linux system, specifically Ubuntu 24.04.

The first step involves installing Docker, which enables you to run the Pro Mosquitto Docker container.

Docker is an application that provides a mechanism for managing containers on your system. It allows you to quickly build, run, and manage containerized applications. It offers an efficient way to deploy software in isolated environments, making it ideal for testing and running applications like Pro Mosquitto.

To install Docker, start by setting up the Docker Engine, the core component for running containers, then proceed with installing the Docker Compose plugin. Refer to this official guide for full instructions on installing the Docker Engine.

Once the installation completes, you can start Docker through the following terminal command:

sudo service docker start

With Docker running, the next step is to log in to the Cedalo registry to access the Pro Mosquitto containers.

A Docker registry is a storage and distribution system for Docker images, which are packaged versions of applications and their dependencies. By logging into the Cedalo registry, you can access specific Docker images that aren’t publicly available. You will need this step to download and run the Pro Mosquitto container.

To access the Cedalo registry, open the Terminal and type the following command:

docker login registry.cedalo.com -u [username provided by us] -p [password provided by us]

If you execute everything correctly, you will see the following:

Successful login into Cedalo registry
Figure 1 – Successful login into Cedalo registry.

While the image shows a successful login, it also displays two warnings:

  • The first warning concerns entering the password through the command line. A more secure method is to use the --password-stdin attribute, which prompts you to enter the password securely.
  • The second warning recommends using a credential helper instead of storing credentials in the config.json file. This docker login reference guide provides more details about configuring a credential helper. 

Now, you can proceed with the Pro Mosquitto installation.

Installing Pro Mosquitto MQTT broker on Ubuntu Linux

This chapter guides you through installing Pro Mosquitto and the publishing and subscribing clients used in the demonstration. It’s important to note that you will use the same client tools available in the open-source version of Mosquitto.

Pro Mosquitto on Ubuntu Linux installation steps

Let’s proceed with installing the latest on-premises Pro Mosquitto trial license from the Cedalo MQTT Platform. If you haven’t registered already, you can request a free trial here to test advanced features of the Pro Mosquitto broker and Management Center for Mosquitto™ web UI.

First, download the package from the link in the email and unzip it. Open the directory, then navigate to mosquitto-2.9-mmc-2.9/unix. Inside, you’ll find several shell scripts to help you manage the Pro Mosquitto containers.

Next, run the following command to download and start the Pro Mosquitto Docker container:

./start.sh up -d

The script initiates the installation process, which involves two steps:

  1. Creating and starting the containers.
  2. Downloading the Docker images from the Cedalo registry.
Starting the Pro Mosquitto Docker containers to install Mosquitto on Ubuntu
Figure 2 – Docker pulling and starting the containers.

If the green text “Started” appears next to the container name at the end of the process, the pull operation was successful, and the Docker container is running. 

Installing Mosquitto clients utilities on Linux

To test the installation, set up two clients to perform the publish and subscribe operations. This guide uses mosquitto_pub and mosquitto_sub applications, which are part of the mosquitto-clients package on Ubuntu. Install the package using the following command:

sudo apt-get install mosquitto-clients

After the installation, verify it by typing mosquitto_pub in the terminal and pressing Enter. You should see the following output:

Verification of the mosquitto-clients package installation
Figure 3 – The mosquitto-clients package is now installed.

Running Pro Mosquitto on Linux

At this point, everything is ready to run Pro Mosquitto on your Linux system. Since the process of starting Mosquitto was covered earlier during the installation steps, the necessary containers should be running. To verify, use the following command:

docker ps --format "{{.Names}}"

The command will list all running containers but filter the output to show only the container’s name. This is useful in making the information more readable since the command returns many other container parameters that are not relevant here.

In this case, the console output will appear as shown, indicating that the Mosquitto containers are running:

List of running docker containers on your Linux system
Figure 4 – Names of running docker containers.

If the containers do not appear, simply restart Mosquitto by executing the same start.sh script. If successful, the previous “docker ps” command will return the two containers.

How to stop Pro Mosquitto in Linux

To stop Pro Mosquitto, navigate to the mosquitto-2.9-mmc-2.9/unix folder and run the following command:

./stop.sh

This command stops the running containers, effectively pausing the entire system. However, the containers remain intact, so you can easily restart them whenever needed.

To remove the containers permanently, use the following command instead:

docker container rm containername

Configuring Pro Mosquitto: the Management Center

Among the Docker containers started with Pro Mosquitto is the Management Center for Mosquitto – a central hub for managing your Pro Mosquitto broker instances and clusters.

It provides a comprehensive web interface that covers the most critical aspects of an IoT project, including security, user and access control management, broker management and monitoring, REST APIs, and more. For more information, visit the Management Center page.

To access the Management Center, simply enter the following address in your web browser: 

http://localhost:8088

After entering your login credentials, located in docker-compose.yml under CEDALO_MC_USERNAME and CEDALO_MC_PASSWORD environment variables, the Management Center will appear, giving you complete control over your Pro Mosquitto setup.

Next, create two new clients: MosquittoPub and MosquittoSub for the publishing and subscribing utilities in the Pro Mosquitto demonstration. Refer to the official client guide for instructions on instantiating new clients.

Testing Pro Mosquitto: Publish and Subscribe

Now that Pro Mosquitto is running, it’s time to test its functionality using the mosquitto-clients tools introduced earlier. You can use mosquitto_sub to subscribe to a topic and mosquitto_pub to publish messages to that topic. This process will verify that your MQTT broker functions correctly and can handle message exchanges.

Subscribe to a topic

First, let’s start by subscribing to a topic. Open a terminal window and use the mosquitto_sub command to subscribe to a topic named /test/topic using the MosquittoSub client:

sudo mosquitto_sub -h localhost -p 1883 -t test/topic -u MosquittoSub -P MosquittoSubPwd

where:

  • -h localhost specifies the hostname where Pro Mosquitto is running.
  • -p 1883 specifies the connection port.
  • -t test/topic sets the topic to which you want to subscribe.
  • -u MosquittoSub specifies the client username. In this case, “MosquittoSub.”
  • -P MosquittoSubPwd specifies the client password. In this case, “MosquittoSubPwd.”

After running this command, the terminal waits for messages published to the topic test/topic. At this point, the subscription is active and ready to receive messages.

Subscribing to "test/topic," using the "mosquitto_sub" command
Figure 6 – Subscribe to the topic test/topic using the mosquitto_sub utility.

Publish a message

Next, open a new terminal window and publish a message to the subscribed topic using the mosquitto_pub command:

sudo mosquitto_pub -h localhost -p 1883 -t test/topic -u MosquittoPub -P MosquittoPubPwd -m 'Hello from Pro Mosquitto'

where:

  • -h localhost specifies the MQTT broker’s hostname.
  • -p 1883 specifies the connection port
  • -t test/topic indicates the topic to which the message will be sent.
  • -u MosquittoPub specifies the client username.
  • -P MosquittoPubPwd specifies the client password.
  • -m 'Hello from Pro Mosquitto' sets the message content.

Once you execute this command, switch back to the first terminal window where you subscribed to the topic. You should see the message “Hello from Pro Mosquitto“, confirming that the Pro Mosquitto broker is functioning correctly.

Subscriber receives the published message
Figure 7 – The subscriber receives the published message.

This simple test demonstrates that Pro Mosquitto can handle publishing and subscribing operations, validating the setup.

Securing Pro Mosquitto on Ubuntu Linux

Securing the Pro Mosquitto MQTT Broker is crucial, especially if your broker is accessible over the internet. Without proper security measures, your broker is at risk of unauthorized access, data breaches, or malicious attacks. Securing Pro Mosquitto protects your data and ensures that only trusted devices and users can communicate with your broker.

This guide explores two critical aspects of securing the Pro Mosquitto broker: authentication and authorization and SSL/TLS encryption.

Configuring authentication and authorization for Pro Mosquitto on Linux

Authentication ensures that only legitimate users or devices can access your MQTT broker. By setting up a username and password, you can control who can connect.

In contrast, authorization determines what each authenticated user is permitted to do—such as publishing messages on specific topics, subscribing to them, etc. Implementing these measures adds a layer of control and prevents unauthorized access. For more details, refer to this authentication and authorization guide.

Enabling SSL/TLS for Pro Mosquitto on Linux

While authentication and authorization allow for an access control mechanism, SSL/TLS encryption secures client and broker communication. SSL/TLS encrypts data exchanges, making it unreadable and unchangeable to anyone who might intercept it. Enabling SSL/TLS prevents potential eavesdropping and safeguarding sensitive information transmitted over the MQTT protocol. Learn more in this article.

Enabling MQTT over WebSockets on Linux

Using MQTT over WebSockets effectively allows web applications running in the browser to communicate with the Pro Mosquitto MQTT broker.

Web browsers don’t natively support the MQTT protocol, but they do support WebSockets, which provide persistent, full-duplex communication between web clients and the MQTT broker. To enable MQTT over WebSockets on your Pro Mosquitto broker, follow this detailed guide.

Troubleshooting common issues

You might encounter some common issues while installing and running Pro Mosquitto with Docker. Here’s how to address them:

1. Docker configurations are not applied: When making changes to a Docker container’s configuration, such as updating settings in the compose YAML file or modifying other configuration files, you must restart the container for the changes to take effect.

Docker containers do not reload configurations automatically, so restarting ensures the container uses the updated settings as intended. To restart the container, use the following command:

./start.sh up -d

2. Credential store issues: A credential store securely manages login credentials, keeping them safe from exposure by storing them in an encrypted format rather than plain text.

However, this tutorial uses the traditional method, which stores credentials directly in the config.json file. This approach can cause issues if the config.json file already contains the credsStore option.

To resolve this, remove the credsStore entry from the file and save it to ensure the credentials work correctly.

Remove the "credsStore : desktop" entry from the "config.json" file for credential store issues
Figure 8 – config.json file of Docker.

Removing the line credsStore : desktop in Figure 10 will address these common issues for a smoother Pro Mosquitto setup with Docker.

Conclusion

This article covers the complete process of installing, configuring, and running the Pro Mosquitto MQTT Broker on Ubuntu Linux using Docker

It provides a comprehensive foundation, from setting up Docker and accessing the Cedalo registry to implementing security measures and enabling MQTT over WebSockets. By following these steps, you’ll have a robust, secure, and flexible MQTT broker setup ready for real-world IoT applications.

Sign up for a Cedalo MQTT Platform trial to explore the advanced features of the Pro Mosquitto broker and the Management Center web UI. Refine your setup and integrate it into your IoT projects for efficient data transmission.

Click to rate this post!
[Total: 0 Average: 0]
About the author
Matteo Trovo Cedalo author

Matteo Trovò

Senior Embedded Software Engineer

Matteo Trovò is a seasoned embedded software engineer with extensive expertise in cybersecurity, computer networks, and data protocols, including MQTT. He is currently employed as a Senior Embedded Software Engineer in the automotive industry in Germany.

After completing a degree in Software Engineering, Matteo gained valuable experience working for various companies, honing his skills in practical settings. During this time, he also supported and contributed to a startup developing MQTT interconnected smart switches for home automation. As the software development lead, Matteo delved deep into MQTT, writing MQTT client software and managing MQTT device networks.

Newsletters icon

Subscribe for monthly updates