Eclipse Mosquitto

​

Overview

• Run it directly to get a managed MQTT broker with sensible defaults
• Inherit it in your own runnable to seamlessly add MQTT messaging to your IoT infrastructure

​

What this template manages

• Mosquitto MQTT broker container (eclipse-mosquitto image, configurable tag)
• Network service on port 1883 (MQTT)
• Network service on port 9001 (WebSocket)
• Persistent volumes for data storage
• Auto-generated configuration file with customizable settings

​

Quick start (run directly)

1. Load templates

monk load MANIFEST

2. Run Mosquitto with defaults

monk run mosquitto/mosquitto-broker

3. Customize configuration (recommended via inheritance)

• Preferred: inherit and override variables as shown below.
• Alternative: fork/clone and edit the variables in mosquitto.yml, then monk load MANIFEST and run.

​

Configuration

variables:
  mqtt-port: 1883                    # MQTT TCP port
  websocket-port: 9001               # WebSocket port for MQTT over WS
  allow-anonymous: true              # Allow connections without authentication
  max-connections: -1                # Maximum concurrent connections (-1 = unlimited)
  persistence: true                  # Enable message persistence
  retain-available: true             # Allow retained messages
  log-level: "information"           # Logging level
  websocket-enabled: true            # Enable WebSocket listener

​

Use by inheritance (recommended for apps)

namespace: myapp
mqtt:
  defines: runnable
  inherits: mosquitto/mosquitto-broker
  variables:
    allow-anonymous:
      value: false
    max-connections:
      value: 1000
sensor-api:
  defines: runnable
  containers:
    api:
      image: myorg/iot-api
  connections:
    message-broker:
      runnable: mqtt
      service: mqtt
  variables:
    mqtt-host:
      value: <- connection-hostname("message-broker")
    mqtt-port:
      value: <- connection-port("message-broker")

monk run myapp/sensor-api

​

Ports and connectivity

• Service: mqtt on TCP port 1883 (default)
• Service: websocket on TCP port 9001 (default)
• From other runnables in the same process group, use connection-hostname("\<connection-name>") to resolve the broker host.

​

Persistence and configuration

• Data path: ${monk-volume-path}/mosquitto/data:/mosquitto/data
• Configuration is auto-generated from template variables and mounted at /mosquitto/config/mosquitto.conf
• Supports message persistence, retained messages, and persistent sessions

​

Features

• MQTT v3.1, v3.1.1, and v5.0 support
• QoS levels 0, 1, and 2
• Retained messages
• Last Will and Testament
• WebSocket support for browser-based clients
• Message persistence
• Configurable connection limits
• Flexible logging

​

Related templates

• Use with microservices for async communication
• Combine with stream processing (Kafka Streams, Flink)
• Integrate with monitoring (prometheus-grafana/)
• Pair with Node-RED for IoT workflow automation

​

Troubleshooting

• If you changed allow-anonymous to false, ensure you have configured authentication (password file or auth plugin) in a custom configuration.
• Ensure the host volumes are writable by the container user.
• For production use, consider setting allow-anonymous: false and configuring proper authentication.
• Check logs:

monk logs -l 500 -f mosquitto/mosquitto-broker