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
------------

``shell
$ npm install mosquitto
`

Usage
-----

`ts
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((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
-------------

$3

The API class construction accepts an argument of type MosquittoConfig:

`ts
/ 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:

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

$3

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

`sh
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:

`sh


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