Mosquitto

Mosquitto MQTT Broker Turnkey Solution

About

This is a Mosquitto turnkey solution, i.e., the combination of an OCI Container ghcr.io/rse/mosquitto and a corresponding TypeScript/JavaScript API mosquitto for use with Node.js, for easily starting an instance of the excellent MQTT broker Eclipse Mosquitto. It was born from the need to have a Mosquitto instance available from within Node.js on the macOS and Linux platforms. The OCI container bundles the Mosquitto program in a portable way. The TypeScript/JavaScript API allows convenient configuration and run-time control of it.

[!NOTE] The TypeScript/JavaScript API requires Mosquitto itself, so this API either requires you to have the mosquitto and mosquitto_passwd commands in your $PATH or requires you to have the docker command in your $PATH (the default).

Installation

$ npm install mosquitto

Usage

import Mosquitto from "mosquitto"
import MQTT      from "mqtt"

/*  start Mosquitto  */
const mosquitto = new Mosquitto()
await mosquitto.start()
await new Promise((resolve) => { setTimeout(resolve, 1000) })

/*  connect to Mosquitto  */
const mqtt = MQTT.connect("mqtt://127.0.0.1:1883", {})
await new Promise<void>((resolve, reject) => {
    mqtt.once("connect", ()    => { resolve() })
    mqtt.once("error",   (err) => { reject(err) })
})
mqtt.end()

/*  stop Mosquitto  */
await mosquitto.stop()
await new Promise((resolve) => { setTimeout(resolve, 1000) })
console.log(mosquitto.logs())

Configuration

TypeScript/JavaScript API

The API class construction accepts an argument of type MosquittoConfig:

/*  Mosquitto configuration types  */
export type MosquittoConfigPasswdEntry = {
    username:     string,
    password:     string
}
export type MosquittoConfigListenEntry = {
    protocol:     "mqtt" | "mqtts" | "ws" | "wss"
    name?:        string
    address:      string
    port:         number
}
export type MosquittoConfig = {
    native:       boolean
    container:    string
    auth:         "builtin" | "plugin"
    persistence:  boolean
    acl:          string
    passwd:       MosquittoConfigPasswdEntry[]
    listen:       MosquittoConfigListenEntry[]
    custom:       string
}

The internal default is:

{
    native:       false,
    container:    "ghcr.io/rse/mosquitto:<version>"
    auth:         "builtin",
    persistence:  false,
    acl:          "",
    passwd:       [ { username: "example", password: "example" } ],
    listen:       [ { protocol: "mqtt", address: "127.0.0.1", port: 1883 } ],
    custom:       ""
}

OCI Container

The OCI Container accepts the following environment variables and their default values:

SUPERVISORD_ETCDIR="/app/etc"
SUPERVISORD_BINDIR="/app/bin"
SUPERVISORD_VARDIR="/app/var"
MOSQUITTO_ETCDIR="/app/etc"
MOSQUITTO_BINDIR="/app/bin"
MOSQUITTO_VARDIR="/app/var"
MOSQUITTO_UID="app"
MOSQUITTO_GID="app"
MOSQUITTO_ADMIN_USERNAME="admin"
MOSQUITTO_ADMIN_PASSWORD="admin"
MOSQUITTO_CUSTOM_USERNAME="example"
MOSQUITTO_CUSTOM_PASSWORD="example"

The OCI Container accepts the following commands:

# start container
$ docker run ghcr.io/rse/mosquitto

# run Mosquitto tools
$ docker run -i -t ghcr.io/rse/mosquitto mosquitto_{pub,sub,rr,passwd,pw}|passwd [...]

# backup/restore data of running container
$ docker exec -i ghcr.io/rse/mosquitto backup|restore [...]

License

Copyright © 2026 Dr. Ralf S. Engelschall Licensed under MIT license