Eclipse Mosquitto

beginner

Lightweight MQTT message broker.

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

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

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

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

Usage Notes

1Docs: https://mosquitto.org/documentation/
2MQTT on port 1883, WebSocket on port 9001
3Create mosquitto.conf: listener 1883 allow_anonymous true
4For auth: password_file /mosquitto/config/passwd
5Create users: docker exec mosquitto mosquitto_passwd -c /mosquitto/config/passwd user1
6Test: 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 notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

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

Components

mosquitto

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download