Mosquitto with Docker Compose

What Mosquitto needs

Only figures Mosquitto's own documentation publishes, each linked to the page it is on. Where the project gives no number, this page does not invent one.

On top of this, Caddy (the reverse proxy in the file) is a single small container.

Which hardware Mosquitto has images for

Read from each image's manifest list in its registry (anonymous, read-only) when this page was built. An app counts for a CPU only if every one of its images lists it.

• x86-64 PC or NAS (linux/amd64): every image has a build.
• Raspberry Pi 4/5, 64-bit OS (linux/arm64): every image has a build.
• Raspberry Pi 3 or Zero 2 W, 32-bit OS (linux/arm/v7): every image has a build; mosquitto only as linux/arm/v6, which Docker pulls on a arm/v7 CPU when there is no arm/v7 build.

A manifest says an image exists for a CPU, not how well Mosquitto runs on it: a build for arm64 or arm/v7 can still be too slow or need more memory than the board has. The RAM and disk Mosquitto publishes are in the table above and, for a whole set of apps against a Raspberry Pi, on Will it run on my machine?. A tag like latest can move to a new digest after the date checked.

docker-compose.yml

This is exactly what the builder writes for Mosquitto alone on example.org: the official definition with its published ports removed except 1883:1883, which cannot go through a web proxy (see below), and Caddy added in front.

# docker-compose.yml built at dankhost.com for: Mosquitto
# Each app block is its official compose definition. Only the names were prefixed with
# the app slug (services, containers, volumes, bind folders, .env variables) so any set of
# apps can share one file; other differences are listed under "Changed:" in each block.
# Caddy publishes 80 and 443. The only other published ports, each labelled where
# it is written: 1883/tcp (Mosquitto: MQTT).
# Secrets live in .env next to this file.

services:
  # ---- Caddy: the one reverse proxy, HTTPS certificates from Let's Encrypt ----
  # Source: https://caddyserver.com/docs/running (checked 2026-09-23)
  # Source: https://github.com/dani-garcia/vaultwarden/wiki/Using-Docker-Compose (checked 2026-09-23)
  # Caddyfile goes in ./caddy/Caddyfile. Fixed address 172.30.0.2 so apps can trust it exactly.
  caddy:
    image: "caddy:2"
    container_name: "caddy"
    restart: "unless-stopped"
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - "./caddy:/etc/caddy"
      - "caddy-data:/data"
      - "caddy-config:/config"
    networks:
      proxy:
        ipv4_address: "172.30.0.2"

  # ---- Mosquitto (mqtt.example.org) ----
  # Source: https://hub.docker.com/_/eclipse-mosquitto (checked 2026-09-29)
  # Source: https://mosquitto.org/man/mosquitto-conf-5.html (checked 2026-09-29)
  # Source: https://mosquitto.org/documentation/authentication-methods/ (checked 2026-09-29)
  # Source: https://github.com/eclipse-mosquitto/mosquitto/blob/master/docker/2.1-alpine/Dockerfile (checked 2026-09-29)
  # Changed: Written from the image page's docker run with the three mirrored directories: ./config, ./data and ./log. Only '1883:1883' is published; Caddy reaches mosquitto:9001, a WebSockets listener added in mosquitto.conf, on the proxy network.
  #          The image page lists no compose file. The tag is 2.1-alpine, one of the two it recommends ("prefer latest or a pinned 2.1*-alpine tag").
  #          Added mosquitto.conf (the image page says to mount your own in /mosquitto/config): the listeners, the persistence and logging lines the page gives, and a password file.
  # PORT OUTSIDE THE PROXY 1883/tcp: plain MQTT for the devices on your network, the '-p 1883:1883' of the documented docker run. MQTT is not HTTP, so most devices cannot reach it through the proxy.
  mosquitto:
    image: "eclipse-mosquitto:2.1-alpine"
    container_name: "mosquitto"
    volumes:
      - "./mosquitto/config:/mosquitto/config"
      - "./mosquitto/data:/mosquitto/data"
      - "./mosquitto/log:/mosquitto/log"
    ports:
      - "1883:1883"  # MQTT
    networks:
      proxy: {}

networks:
  # Pinned so the trusted-proxy address given to each app (172.30.0.2) is exact.
  # If "docker compose up" reports "Pool overlaps", change 172.30.0 here, in Caddy's
  # ipv4_address and in every trusted-proxy value to a free 172.x.0 range.
  proxy:
    ipam:
      config:
        - subnet: "172.30.0.0/24"
          ip_range: "172.30.0.128/25"
          gateway: "172.30.0.1"

volumes:
  caddy-data:
  caddy-config:

Caddyfile save as caddy/Caddyfile

Caddy gets and renews the HTTPS certificate for mqtt.example.org by itself once the DNS record points at your server and ports 80 and 443 reach it.

# Caddyfile built at dankhost.com. Save it as ./caddy/Caddyfile next to docker-compose.yml.
# Caddy gets and renews a Let's Encrypt certificate for each name below by itself,
# once the DNS records point at this server and ports 80 and 443 reach it.

# Mosquitto
mqtt.example.org {
	reverse_proxy mosquitto:9001
}

Already running nginx, Nginx Proxy Manager, Caddy or Traefik? The reverse-proxy settings Mosquitto needs, for all four, each cited to Mosquitto's own docs.

.env

Mosquitto needs no secret here; the builder adds nothing you have to fill in by hand.

# .env for Mosquitto, from dankhost.com/app/mosquitto/. Nothing here is secret.
# Keep this file private (chmod 600).
# None of the chosen apps needs a variable here.

The file Mosquitto needs next to the compose file

The builder writes it with your domain and fills every secret with random letters and digits made in your browser (crypto.getRandomValues); nothing is sent anywhere. Below, each secret is a FILL-IN-… placeholder instead, because a secret printed on a public page is the same for everyone who copies it.

./mosquitto/config/mosquitto.conf

# mosquitto.conf for Mosquitto, built at dankhost.com. Save it as ./mosquitto/config/mosquitto.conf
# Every line is an option from the mosquitto.conf man page.
# Plain MQTT for devices on your network (published on the host as 1883).
listener 1883
# MQTT over WebSockets, which the proxy serves as wss://mqtt.example.org.
listener 9001
protocol websockets
# The Docker image page: persist data to /mosquitto/data and log to /mosquitto/log.
persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log
# allow_anonymous defaults to false: only users in this file can connect.
# Create it before the first start (see the notes).
password_file /mosquitto/config/passwd

What Mosquitto needs beyond the proxy

Every other app in the builder is reached only through the proxy on ports 80 and 443. Mosquitto also needs this port on the server itself, because it carries traffic that is not HTTP. The compose file labels it with a # PORT OUTSIDE THE PROXY comment.

• 1883:1883 (MQTT): plain MQTT for the devices on your network, the '-p 1883:1883' of the documented docker run. MQTT is not HTTP, so most devices cannot reach it through the proxy.
• Port 1883 (plain MQTT, not encrypted) is published on every interface of this server for the devices on your network. Do not forward it from your router; clients outside your home use MQTT over WebSockets through the proxy on port 443 instead.

Changes from the official file

Besides prefixing every service, container, volume, folder and variable with mosquitto (so any set of apps can share one file), these are all the differences from what the project documents:

• Written from the image page's docker run with the three mirrored directories: ./config, ./data and ./log. Only '1883:1883' is published; Caddy reaches mosquitto:9001, a WebSockets listener added in mosquitto.conf, on the proxy network.
• The image page lists no compose file. The tag is 2.1-alpine, one of the two it recommends ("prefer latest or a pinned 2.1*-alpine tag").
• Added mosquitto.conf (the image page says to mount your own in /mosquitto/config): the listeners, the persistence and logging lines the page gives, and a password file.

Notes for Mosquitto behind the proxy

• Before the first start, create a user: docker compose run --rm mosquitto mosquitto_passwd -c /mosquitto/config/passwd <user> (it asks for the password). The authentication page: the password file must be readable by the user Mosquitto runs as, which in this image is uid 1883, so then run: sudo chown 1883:1883 ./mosquitto/config/passwd
• Without that file Mosquitto does not start: the configuration names it, and since allow_anonymous defaults to false no client could connect anyway. Add more users with the same command without -c.
• Devices on your network connect to the server's LAN address on port 1883 with that user. Clients that speak MQTT over WebSockets connect to wss://mqtt.example.org (port 443, through the proxy).
• Other apps in the same compose file reach the broker as mosquitto:1883 on the proxy network, for example Zigbee2MQTT with mqtt://mosquitto:1883. Home Assistant (host network) reaches it at this server's LAN address, port 1883.
• The documented docker run sets no restart policy, so Mosquitto does not come back by itself after a reboot. Run "docker compose up -d" again, or add restart: unless-stopped.

Back it up

Mosquitto publishes no backup procedure. With persistence on, its data file (retained messages, subscriptions, queued messages for persistent clients) is in /mosquitto/data; the configuration and password file are in /mosquitto/config.

Below is the BACKUP.md the builder writes next to the compose file above: which of its folders and volumes hold data, what to copy with which container stopped, and a restore check. Pick more apps in the builder and it covers them all in one file.

# BACKUP.md built at dankhost.com for: Mosquitto

What to copy from the docker-compose.yml built with this file, the database dump each project documents (rewritten for the service names in that file), what to copy with which container stopped, and how to check the result. Run every command in the folder that holds docker-compose.yml.

The folders are owned by the containers' users: put sudo in front of tar if it says "Permission denied". Named volumes live under /var/lib/docker/volumes, not next to the compose file, so they are copied through a throwaway ubuntu container (Docker's documented --volumes-from method). tar makes a full copy each run; for large folders an incremental tool (restic, borg, rsync) saves time and space.

Never run "docker compose down -v" on this file: it deletes the named volumes of every app in it.

## Before you start

    BACKUP=/mnt/backup/selfhost   # change this: a disk or machine other than this server's system disk
    mkdir -p "$BACKUP"

## Every time: the three stack files

    tar czf "$BACKUP/stack-files.tar.gz" docker-compose.yml .env caddy

.env holds the database passwords and secret keys the apps were set up with; keep this archive as private as the data.

## Caddy (the reverse proxy)

Caddy's docs: 'The data directory must not be treated as a cache.' It holds the TLS certificates and their private keys; without it Caddy has to ask Let's Encrypt for every certificate again.

- caddy-data (named volume, /data in caddy)
  BACK UP: TLS certificates, private keys, OCSP staples.
- caddy-config (named volume, /config in caddy)
  SKIP: the last active configuration, kept for 'caddy run --resume', which this setup does not use: it starts from the Caddyfile.
- ./caddy (/etc/caddy in caddy)
  IN stack-files.tar.gz: the Caddyfile, copied with the stack files above.

Copy (Caddy keeps serving while you copy):

    docker run --rm --volumes-from caddy -v "$BACKUP":/backup ubuntu tar cvf /backup/caddy-data.tar /data

Restore check:

    tar tf "$BACKUP/caddy-data.tar" > /dev/null && echo OK
    docker run --rm --volumes-from caddy -v "$BACKUP":/backup ubuntu bash -c "cd /data && tar xvf /backup/caddy-data.tar --strip 1"

Sources:
- Caddy docs: Conventions, Data directory: https://caddyserver.com/docs/conventions#data-directory (checked 2026-09-24)
- Docker docs: Volumes, Back up, restore, or migrate data volumes: https://docs.docker.com/engine/storage/volumes/#back-up-restore-or-migrate-data-volumes (checked 2026-09-24)

## Mosquitto

Mosquitto publishes no backup procedure. With persistence on, its data file (retained messages, subscriptions, queued messages for persistent clients) is in /mosquitto/data; the configuration and password file are in /mosquitto/config.

What this compose mounts:
- ./mosquitto/config (/mosquitto/config in mosquitto)
  BACK UP: mosquitto.conf and the password file.
- ./mosquitto/data (/mosquitto/data in mosquitto)
  BACK UP: mosquitto.db: retained messages and persistent sessions.
- ./mosquitto/log (/mosquitto/log in mosquitto)
  SKIP: the log file.

1. Stop mosquitto. Mosquitto writes its persistence file while it runs; stopping it first writes out a complete copy.

    docker compose stop mosquitto

2. Copy while mosquitto is stopped:

    tar czf "$BACKUP/mosquitto-config.tar.gz" ./mosquitto/config
    tar czf "$BACKUP/mosquitto-data.tar.gz" ./mosquitto/data

3. Start it again:

    docker compose start mosquitto

Restore check:

    tar tzf "$BACKUP/mosquitto-config.tar.gz" > /dev/null && echo OK
    tar tzf "$BACKUP/mosquitto-data.tar.gz" > /dev/null && echo OK

Put a copy back (with mosquitto stopped):

    tar xzf "$BACKUP/mosquitto-config.tar.gz"   # recreates ./mosquitto/config; move the old folder aside first
    tar xzf "$BACKUP/mosquitto-data.tar.gz"   # recreates ./mosquitto/data; move the old folder aside first

Stop it, put ./mosquitto/config and ./mosquitto/data back, start it.

Sources:
- Mosquitto docs: mosquitto.conf man page (listener, protocol websockets, allow_anonymous, password_file, persistence): https://mosquitto.org/man/mosquitto-conf-5.html (checked 2026-09-29)
- Docker docs: Volumes, Back up, restore, or migrate data volumes: https://docs.docker.com/engine/storage/volumes/#back-up-restore-or-migrate-data-volumes (checked 2026-09-29)

Sources

Every page below was fetched on the date shown.

• mosquitto.org front page checked 2026-09-29 (what it does)
• Docker Hub: eclipse-mosquitto official image (directories, docker run, image tags) checked 2026-09-29 (compose definition and proxy settings)
• Mosquitto docs: mosquitto.conf man page (listener, protocol websockets, allow_anonymous, password_file, persistence) checked 2026-09-29 (compose definition and proxy settings, backup plan)
• Mosquitto docs: Authentication methods (mosquitto_passwd, password_file) checked 2026-09-29 (compose definition and proxy settings)
• Mosquitto repository: docker/2.1-alpine/Dockerfile (the mosquitto user is uid 1883; volumes /mosquitto/data and /mosquitto/log) checked 2026-09-29 (compose definition and proxy settings)
• Caddy docs: Keep Caddy running (Docker Compose section) checked 2026-09-23 (Caddy)
• Vaultwarden wiki: Caddy with HTTP challenge (uses the caddy:2 image) checked 2026-09-23 (Caddy)
• Docker docs: Volumes, Back up, restore, or migrate data volumes checked 2026-09-29 (backup plan)
• Caddy docs: Conventions, Data directory checked 2026-09-24 (backup plan)

Add Mosquitto to the builder All fifty apps