luongnv89/mosquitto-mqtt-broker repository overview

⁠Mosquitto MQTT Broker

A lightweight, secure Docker container for the Mosquitto MQTT broker based on Alpine Linux.

⁠Features

• Lightweight: Based on Alpine Linux 3.21 (~5MB image)
• Secure: Runs as non-root user with proper permissions
• Simple: Minimal configuration, ready to use
• Standards Compliant: Uses Mosquitto 2.0.20 MQTT broker

⁠Quick Start

⁠Pull and Run

docker run --rm -d -p 1882:1883 luongnv89/mosquitto-mqtt-broker

⁠Build from Source

# Clone the repository
git clone https://github.com/luongnv89/mosquitto-mqtt-broker.git
cd mosquitto-mqtt-broker

# Build the image
docker build -t luongnv89/mosquitto-mqtt-broker .

# Run the container
docker run --rm -d -p 1882:1883 luongnv89/mosquitto-mqtt-broker

⁠Usage

⁠Basic Usage

Run the broker in detached mode:

docker run --rm -d --name mosquitto -p 1883:1883 luongnv89/mosquitto-mqtt-broker

⁠Custom Port Mapping

Map to a different host port:

docker run --rm -d --name mosquitto -p 8883:1883 luongnv89/mosquitto-mqtt-broker

⁠Persistent Data

Mount volumes for persistent data and logs:

docker run --rm -d --name mosquitto \
  -p 1883:1883 \
  -v $(pwd)/data:/mosquitto/data \
  -v $(pwd)/log:/mosquitto/log \
  luongnv89/mosquitto-mqtt-broker

⁠View Logs

docker logs mosquitto

⁠Testing the Broker

⁠Install Mosquitto Clients

macOS:

brew install mosquitto

Ubuntu/Debian:

apt-get install mosquitto-clients

⁠Subscribe to a Topic

Open a terminal and subscribe to a test topic:

mosquitto_sub -h localhost -p 1883 -t test/topic

⁠Publish a Message

In another terminal, publish a message:

mosquitto_pub -h localhost -p 1883 -t test/topic -m "Hello MQTT!"

You should see the message appear in the subscriber terminal.

⁠Security Considerations

⚠️ Important: This container runs with default Mosquitto configuration:

• No authentication - Open broker, anyone can connect
• Local only mode by default - Only localhost connections allowed
• No encryption - Plain TCP connections

⁠Production-Ready Security Setup

This repository includes example configuration files and a setup script to help you quickly configure a secure MQTT broker.

⁠Quick Setup (Automated)

Use the provided setup script to configure security automatically:

# Run the setup script
./setup-security.sh

The script will:

1. Create a config directory with secure configuration files
2. Generate a password file with an admin user
3. Set up ACL (Access Control List) for topic permissions
4. Create directories for data persistence and logs

After running the script, start the broker with:

docker run -d --name mosquitto \
  -p 1883:1883 \
  -v $(pwd)/config:/mosquitto/config \
  -v $(pwd)/data:/mosquitto/data \
  -v $(pwd)/log:/mosquitto/log \
  luongnv89/mosquitto-mqtt-broker \
  -c /mosquitto/config/mosquitto.conf

⁠Manual Setup

If you prefer to set up security manually:

1. Create configuration files:

mkdir -p config data log
cp mosquitto.conf.example config/mosquitto.conf
cp acl.example config/acl

2. Create password file and add users:

# Create password file with first user (admin)
docker run --rm -v $(pwd)/config:/mosquitto/config \
  luongnv89/mosquitto-mqtt-broker \
  mosquitto_passwd -c /mosquitto/config/passwd admin

# Add additional users (without -c flag)
docker run --rm -v $(pwd)/config:/mosquitto/config \
  luongnv89/mosquitto-mqtt-broker \
  mosquitto_passwd /mosquitto/config/passwd publisher

3. Edit ACL file (config/acl) to define topic permissions:

# Admin has full access
user admin
topic readwrite #

# Publisher can only write to sensor topics
user publisher
topic write sensor/#

# Subscriber can only read from sensor topics
user subscriber
topic read sensor/#

4. Start the broker with secure configuration:

docker run -d --name mosquitto \
  -p 1883:1883 \
  -v $(pwd)/config:/mosquitto/config \
  -v $(pwd)/data:/mosquitto/data \
  -v $(pwd)/log:/mosquitto/log \
  luongnv89/mosquitto-mqtt-broker \
  -c /mosquitto/config/mosquitto.conf

5. Test with authentication:

# Subscribe with authentication
mosquitto_sub -h localhost -p 1883 -u admin -P <password> -t test/topic

# Publish with authentication
mosquitto_pub -h localhost -p 1883 -u admin -P <password> -t test/topic -m "Secure message"

⁠Security Features in Example Configuration

The example configuration (mosquitto.conf.example) includes:

• ✅ Authentication required - No anonymous connections
• ✅ Access Control Lists (ACL) - Topic-level permissions per user
• ✅ Persistence enabled - Messages survive broker restarts
• ✅ Detailed logging - Track connections and errors
• ✅ TLS/SSL ready - Commented configuration for encryption
• ✅ WebSocket support - Optional MQTT over WebSockets
• ✅ Bridge configuration - Connect to other MQTT brokers

⁠Managing Users

Add a new user:

docker run --rm -v $(pwd)/config:/mosquitto/config \
  luongnv89/mosquitto-mqtt-broker \
  mosquitto_passwd /mosquitto/config/passwd <username>

Change user password:

docker run --rm -v $(pwd)/config:/mosquitto/config \
  luongnv89/mosquitto-mqtt-broker \
  mosquitto_passwd /mosquitto/config/passwd <username>

Delete a user:

docker run --rm -v $(pwd)/config:/mosquitto/config \
  luongnv89/mosquitto-mqtt-broker \
  mosquitto_passwd -D /mosquitto/config/passwd <username>

⁠Container Details

• Base Image: alpine:3.21
• MQTT Broker: Mosquitto 2.0.20
• Exposed Port: 1883 (MQTT)
• User: mosquitto (non-root)
• Working Directory: /mosquitto
• Data Directory: /mosquitto/data
• Log Directory: /mosquitto/log
• Platforms: linux/amd64, linux/arm64, linux/arm/v7

⁠Continuous Integration

This repository uses GitHub Actions for automated builds and deployments:

• ✅ Automatic builds on every push to master
• ✅ Multi-platform support (amd64, arm64, arm/v7)
• ✅ Tagged releases with semantic versioning
• ✅ Security scanning with Docker Scout
• ✅ Automated deployment to Docker Hub

For setup instructions, see GITHUB_ACTIONS_SETUP.md⁠

⁠Security Scanning

This image is regularly scanned with Docker Scout:

• ✅ 0 Critical vulnerabilities
• ✅ 0 High vulnerabilities
• ✅ 0 Medium vulnerabilities
• ℹ️ 2 Low vulnerabilities (busybox - no fix available)

⁠License

See LICENSE⁠ file for details.

⁠Links

• Mosquitto Documentation⁠
• MQTT Protocol⁠
• Docker Hub⁠