$docker.recipes

Eclipse Mosquitto

beginner

Lightweight MQTT message broker.

[i]Overview

Eclipse Mosquitto is an open-source message broker that implements the MQTT (Message Queuing Telemetry Transport) protocol, originally developed by IBM and standardized by OASIS. As one of the most lightweight and efficient MQTT brokers available, Mosquitto serves as a central hub for IoT devices, sensors, and applications to communicate through publish-subscribe messaging patterns. The broker handles message routing between publishers and subscribers with minimal resource overhead, making it ideal for resource-constrained environments and large-scale IoT deployments. This Docker deployment creates a complete MQTT messaging infrastructure with both traditional TCP connections on port 1883 and WebSocket support on port 9001. The configuration enables real-time bidirectional communication between IoT devices, web applications, mobile apps, and backend services through a standardized messaging protocol. The setup includes persistent data storage for message retention, configurable logging, and external configuration management through mounted volumes. Developers building IoT applications, system integrators deploying sensor networks, and organizations implementing real-time messaging systems will benefit from this deployment. The combination of Mosquitto's proven reliability with Docker's portability makes it suitable for everything from home automation systems to industrial IoT platforms, providing the messaging backbone needed for distributed device communication and event-driven architectures.

[*]Key Features

  • [+]MQTT v3.1, v3.1.1, and v5.0 protocol support with full specification compliance
  • [+]WebSocket transport layer enabling MQTT over HTTP for web browser clients
  • [+]Quality of Service levels 0, 1, and 2 for reliable message delivery guarantees
  • [+]Retained message support for last known good values and device state persistence
  • [+]Topic-based message filtering with wildcard subscription patterns
  • [+]Built-in authentication and authorization with password files and ACL support
  • [+]Message persistence and offline client session management
  • [+]Bridge functionality for connecting multiple Mosquitto brokers together

[#]Common Use Cases

  • [1]IoT device telemetry collection and command distribution for smart home systems
  • [2]Industrial sensor monitoring and equipment control in manufacturing environments
  • [3]Real-time chat applications and notification systems using MQTT over WebSockets
  • [4]Vehicle tracking and fleet management with GPS coordinate publishing
  • [5]Environmental monitoring networks collecting temperature, humidity, and air quality data
  • [6]Smart agriculture systems coordinating irrigation, lighting, and climate control
  • [7]Healthcare IoT deployments for patient monitoring and medical device integration

[!]Prerequisites

  • [!]Docker Engine 20.10+ and Docker Compose v2.0+ installed on the host system
  • [!]Minimum 256MB RAM available for the Mosquitto broker process
  • [!]Network ports 1883 (MQTT) and 9001 (WebSockets) accessible and not in use
  • [!]Basic understanding of MQTT protocol concepts including topics and QoS levels
  • [!]File system permissions allowing Docker to create and mount configuration directories
  • [!]MQTT client tools installed for testing (mosquitto-clients package or equivalent)
[!]

WARNING: For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

[$]docker-compose.yml

[docker-compose.yml]
1services: 
2  mosquitto: 
3    image: eclipse-mosquitto:latest
4    container_name: mosquitto
5    restart: unless-stopped
6    volumes: 
7      - ./mosquitto/config:/mosquitto/config
8      - mosquitto_data:/mosquitto/data
9      - mosquitto_log:/mosquitto/log
10    ports: 
11      - "1883:1883"
12      - "9001:9001"
13
14volumes: 
15  mosquitto_data: 
16  mosquitto_log:

[$].env Template

[.env]
1# Create mosquitto/config/mosquitto.conf

[i]Usage Notes

  1. [1]Docs: https://mosquitto.org/documentation/
  2. [2]MQTT on port 1883, WebSocket on port 9001
  3. [3]Create mosquitto.conf: listener 1883 allow_anonymous true
  4. [4]For auth: password_file /mosquitto/config/passwd
  5. [5]Create users: docker exec mosquitto mosquitto_passwd -c /mosquitto/config/passwd user1
  6. [6]Test: mosquitto_pub -t test -m 'hello', mosquitto_sub -t test

[>]Quick Start

[terminal]
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  mosquitto:
5    image: eclipse-mosquitto:latest
6    container_name: mosquitto
7    restart: unless-stopped
8    volumes:
9      - ./mosquitto/config:/mosquitto/config
10      - mosquitto_data:/mosquitto/data
11      - mosquitto_log:/mosquitto/log
12    ports:
13      - "1883:1883"
14      - "9001:9001"
15
16volumes:
17  mosquitto_data:
18  mosquitto_log:
19EOF
20
21# 2. Create the .env file
22cat > .env << 'EOF'
23# Create mosquitto/config/mosquitto.conf
24EOF
25
26# 3. Start the services
27docker compose up -d
28
29# 4. View logs
30docker compose logs -f

[>]One-Liner

Run this command to download and set up the recipe in one step:

[terminal]
1curl -fsSL https://docker.recipes/api/recipes/mosquitto/run | bash

[?]Troubleshooting

  • [!]Connection refused on port 1883: Verify the mosquitto.conf contains 'listener 1883' directive and container is running
  • [!]Authentication failures with valid credentials: Check that password file permissions are readable by mosquitto user (UID 1883)
  • [!]WebSocket connections failing on port 9001: Add 'listener 9001' and 'protocol websockets' to mosquitto.conf
  • [!]Messages not persisting after container restart: Ensure mosquitto_data volume is properly mounted to /mosquitto/data
  • [!]Permission denied errors on startup: Set correct ownership on config directory with 'chown -R 1883:1883 ./mosquitto/config'
  • [!]High memory usage with retained messages: Configure 'max_queued_messages' and 'message_size_limit' in mosquitto.conf

Community Notes

Loading...
Loading notes...

## Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

## Components

mosquitto

## Tags

#mosquitto#mqtt#iot#messaging

## Category

Message Queues & Brokers

## Related