Exécuter Mosquitto dans Docker (docker run et docker-compose)

Docker est le moyen le plus rapide d’obtenir un broker MQTT jetable et reproductible. L’image officielle eclipse-mosquitto est légère et bien maintenue, mais ses réglages par défaut surprennent presque tout le monde la première fois : sans fichier de configuration, impossible de se connecter depuis l’extérieur du conteneur. Ce guide met en place Mosquitto dans Docker correctement — avec des volumes persistants, des ports TCP et WebSocket et une authentification par mot de passe.

1. Créer l’arborescence de dossiers

L’image attend trois répertoires sous /mosquitto. Reproduisez-les sur l’hôte :

mkdir -p mosquitto/config mosquitto/data mosquitto/log
touch mosquitto/config/mosquitto.conf

2. Écrire un mosquitto.conf minimal

Mosquitto 2.x n’écoute que sur localhost quand aucun listener n’est configuré — dans un conteneur, cela signifie que personne ne peut le joindre. Cette configuration ouvre MQTT sur 1883 et les WebSockets sur 9001 :

# MQTT over TCP
listener 1883
# MQTT over WebSockets
listener 9001
protocol websockets

persistence true
persistence_location /mosquitto/data/

log_dest file /mosquitto/log/mosquitto.log
log_dest stdout

# For a first test only — switched to a password file in step 5
allow_anonymous true

Besoin de TLS, d’ACL ou de réglages de bridge ? Le générateur de mosquitto.conf construit un fichier valide à partir d’un formulaire, et le guide d’installation explique plus en détail le mode local uniquement.

3. Le démarrer avec docker run

docker run -d --name mosquitto \
  --restart unless-stopped \
  -p 1883:1883 -p 9001:9001 \
  -v "$PWD/mosquitto/config:/mosquitto/config" \
  -v "$PWD/mosquitto/data:/mosquitto/data" \
  -v "$PWD/mosquitto/log:/mosquitto/log" \
  eclipse-mosquitto:2

Fixer le tag de version majeure (eclipse-mosquitto:2) évite les mises à jour surprises. Consultez les journaux avec docker logs -f mosquitto ; vous devriez voir Opening ipv4 listen socket on port 1883 et une ligne websockets pour le port 9001.

4. Ou utiliser Docker Compose

Au-delà d’un test rapide, un fichier Compose est plus facile à garder sous contrôle de version :

services:
  mosquitto:
    image: eclipse-mosquitto:2
    container_name: mosquitto
    restart: unless-stopped
    ports:
      - "1883:1883"   # MQTT
      - "9001:9001"   # MQTT over WebSockets
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
      - ./mosquitto/log:/mosquitto/log

docker compose up -d
docker compose logs -f mosquitto

Les autres services du même projet Compose (Node-RED, Home Assistant, votre application) joignent le broker par son nom de service : mqtt://mosquitto:1883. Ne publiez sur l’hôte que les ports dont quelque chose en dehors de Docker a réellement besoin.

5. Ajouter un fichier de mots de passe via docker exec

L’accès anonyme convient pour une minute de test, jamais plus. Créez un utilisateur avec mosquitto_passwd, fourni dans l’image :

# -c creates the file (overwrites it if it exists!) — use only for the first user
docker exec -it mosquitto mosquitto_passwd -c /mosquitto/config/passwd alice

# add more users without -c
docker exec -it mosquitto mosquitto_passwd /mosquitto/config/passwd bob

Passez ensuite la configuration de l’accès anonyme à l’authentification par mot de passe :

allow_anonymous false
password_file /mosquitto/config/passwd

docker restart mosquitto

Les ACL et TLS fonctionnent de la même façon — les fichiers vont dans le volume de configuration. Voir sécuriser Mosquitto avec mots de passe, ACL et TLS.

6. Tester le conteneur

Depuis l’hôte (avec les clients Mosquitto installés) :

mosquitto_sub -h localhost -p 1883 -u alice -P 'secret' -t 'demo/#' -v &
mosquitto_pub -h localhost -p 1883 -u alice -P 'secret' -t 'demo/hello' -m 'hi from docker'

Pas de clients sur l’hôte ? Utilisez ceux du conteneur :

docker exec -it mosquitto mosquitto_sub -h localhost -u alice -P 'secret' -t 'demo/#' -v

Le listener WebSocket sur 9001 est celui qu’utilisent les clients navigateur (ws://<host>:9001). Gardez à l’esprit qu’une page chargée en HTTPS ne peut ouvrir que des connexions wss:// : tester un broker local depuis un client web hébergé nécessite donc généralement TLS devant le port 9001 — plus de détails dans MQTT sur WebSockets. Pour voir à quoi ressemble un aller-retour fonctionnel dans le navigateur, essayez d’abord un broker public :

Essayez-le dans le client MQTT en ligne

Dépanner le conteneur

Pour les autres codes CONNACK, la référence des codes de raison MQTT et le guide des erreurs de connexion expliquent ce que le broker vous dit.

Mettre à jour l’image

Comme la configuration, les données et les journaux vivent sur l’hôte, mettre à jour revient simplement à tirer une image plus récente et à recréer le conteneur. Les messages retenus et les sessions persistantes survivent tant que le volume data est conservé :

docker compose pull mosquitto
docker compose up -d mosquitto
docker compose logs --tail 20 mosquitto

Avec un simple docker run, tirez l’image, puis lancez docker rm -f mosquitto et relancez la même commande docker run. Garder cette commande dans un petit script shell (ou passer à Compose) vous évite de retaper les options de volume.

Conseils pour la production

• Fixez un tag d’image exact et mettez à jour délibérément ; lisez le changelog de Mosquitto avant les mises à jour majeures.
• Gardez data sur un volume, sinon les messages retenus et les sessions persistantes disparaissent à la recréation du conteneur.
• Mettez TLS sur 8883 (et sur le listener WebSocket) avant d’exposer quoi que ce soit sur Internet — voir les ports MQTT pour les conventions.
• Pour déboguer, lisez docker logs mosquitto plutôt que de lancer mosquitto -v via docker exec — cela démarre un second broker dans le conteneur, qui échoue avec « address already in use ».

Questions fréquentes