Mosquitto Setup Guide

Mosquitto Service Overview

Eclipse Mosquitto is a lightweight, open-source MQTT message broker. It acts as the central communication hub for smart home devices, IoT hardware, and automation services across your network.

---

Key Features & Requirements

• Local-First Messaging: Routes telemetry and commands locally between smart home integrations without cloud latency.
• Integrations: Essential backend broker for services like Home Assistant, Frigate NVR, Govee2MQTT, and Zigbee2MQTT.
• Persistence: Preserves retained device states across container updates and system reboots when enabled.
• Network Ports:
  • 1883: Standard unencrypted MQTT protocol listener port.
  • 9001: MQTT over WebSockets listener port.

---

Step 1: Deploy Service Template & Configuration

1. Copy the mosquitto.yaml template into your active server compose directory:

cp compose/templates/mosquitto.yaml compose/server1/mosquitto.yaml

2. Create the target configuration directory if it doesn't exist yet:

mkdir -p ${DOCKERDIR}/mosquitto/config ${DOCKERDIR}/mosquitto/data

3. Copy the starter configuration template from your repository's scripts/ directory to the live data path:

cp scripts/mosquitto_config_example.conf ${DOCKERDIR}/mosquitto/config/mosquitto.conf

---

Step 2: Configuration Reference (mosquitto.conf)

Below is the standard configuration contained in mosquitto_config_example.conf:

# Mosquitto MQTT Broker Configuration
# Place this file at: ${DOCKERDIR}/mosquitto/config/mosquitto.conf

# Port Listener
listener 1883

# Allow unauthenticated local connections
allow_anonymous true

# Detailed Logging
log_type all

# Retain topic states across container restarts
persistence true
persistence_location /mosquitto/data/

---

Step 3: Service Definition

# ------------------------------------------------------------------------------
# Mosquitto - MQTT Broker
# ------------------------------------------------------------------------------
# This container runs Eclipse Mosquitto, a lightweight MQTT broker for
# local messaging between smart devices and services.
#
# Key Features:
# - Lightweight and fast
# - Local-first messaging for IoT and automation
# - Compatible with Home Assistant, Govee2MQTT, Zigbee2MQTT, etc.
#
# Notes:
# - Listens on port 1883 (MQTT) and 9001 (WebSocket)
# - Configuration lives in ${DOCKERDIR}/mosquitto/config
# ------------------------------------------------------------------------------
services:
  mosquitto:
    container_name: mosquitto.${HOST_NAME}
    hostname: mosquitto.${HOST_NAME}.lan
    image: eclipse-mosquitto:latest
    environment:
      PUID: ${PUID}
      PGID: ${PGID}
      TZ: ${TZ}
    volumes:
      - ${DOCKERDIR}/mosquitto/config:/mosquitto/config
      - ${DOCKERDIR}/mosquitto/data:/mosquitto/data
      - ${DOCKERDIR}/logs/mosquitto:/mosquitto/log
    networks:
      - mediaserver
    ports:
      - "1883:1883"
      - "9001:9001"
    restart: always
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    labels:
      - "com.centurylinklabs.watchtower.enable=true"

---

Deployment Commands

Launch or update the container using your project stack flag:

• Deploy Service:

  docker compose -p mediaserver -f docker-compose-server1.yaml up -d mosquitto

• View Live Connection Logs:

  docker compose -p mediaserver -f docker-compose-server1.yaml logs -f mosquitto