Skip to main content
Mini PC Lab logo
Mini PC LabMini PCs for Homelabs
tutorials

How to Set Up Mosquitto Mqtt on Mini PC

By Max · May 2, 2026 · Updated May 5, 2026

This article contains affiliate links. If you purchase through our links, we may earn a commission at no extra cost to you. We only recommend products we’ve thoroughly researched and verified.

How to set up Mosquitto MQTT broker on a mini PC hero image

MQTT is the message bus that connects your smart home devices. Zigbee2MQTT, Tasmota switches, WLED strips, and Shelly devices all publish state updates and receive commands through a central MQTT broker. Running Mosquitto on a mini PC gives you a reliable, low-latency hub for your entire IoT fleet — at about 20MB of RAM, it’s the lightest service on the stack.

This guide deploys Mosquitto via Docker, secures it with username/password authentication, and connects it to Home Assistant and Zigbee2MQTT.

What you need:

  • A mini PC running Ubuntu Server 24.04 LTS with Docker installed
  • Home Assistant running Docker or HAOS on a different machine
  • Optional: a Zigbee USB stick CC2652P or similar

When to Use This Guide vs the HAOS Add-on

Use the HAOS Mosquitto add-on if:

  • You run Home Assistant OS or Supervised
  • You want one-click setup with automatic HA integration

Use standalone Docker Mosquitto if:

  • You run Home Assistant Container
  • You want Mosquitto isolated from HA on a separate machine
  • You need Mosquitto to serve multiple automation platforms

This guide covers the Docker standalone setup.

Step 1: Create the Mosquitto Configuration

mkdir -p ~/mosquitto/{config,data,log}

Create the configuration file:

nano ~/mosquitto/config/mosquitto.conf
# Network
listener 1883
listener 8883
protocol mqtt

# Authentication — no anonymous connections
allow_anonymous false
password_file /mosquitto/config/password_file

# Persistence
persistence true
persistence_location /mosquitto/data/

# Logging
log_dest file /mosquitto/log/mosquitto.log
log_dest stdout
log_type error
log_type warning
log_type notice
log_type information

Step 2: Create User Credentials

Create the password file with an initial user. The container’s mosquitto_passwd tool generates the hashed password:

# Create empty password file first
touch ~/mosquitto/config/password_file

# Add the homeassistant user (replace with a strong password)
docker run --rm -v ~/mosquitto/config:/mosquitto/config \
  eclipse-mosquitto:2 \
  mosquitto_passwd -b /mosquitto/config/password_file homeassistant YOUR-STRONG-PASSWORD

# Add a Zigbee2MQTT user
docker run --rm -v ~/mosquitto/config:/mosquitto/config \
  eclipse-mosquitto:2 \
  mosquitto_passwd -b /mosquitto/config/password_file zigbee2mqtt YOUR-Z2M-PASSWORD

Verify the file was created:

cat ~/mosquitto/config/password_file
# Should show two lines with hashed passwords

Step 3: Deploy Mosquitto

nano ~/mosquitto/docker-compose.yml
services:
  mosquitto:
    image: eclipse-mosquitto:2
    container_name: mosquitto
    ports:
      - "1883:1883"   # MQTT (LAN only — do not expose to internet)
      - "8883:8883"   # MQTT over TLS (for external clients if needed)
    volumes:
      - ./config:/mosquitto/config
      - ./data:/mosquitto/data
      - ./log:/mosquitto/log
    restart: unless-stopped
cd ~/mosquitto
docker compose up -d
docker compose logs -f  # Watch startup — should show "mosquitto version 2.x starting"

Test the connection from the host:

# Install mosquitto clients
sudo apt install -y mosquitto-clients

# Subscribe to a test topic (leave running in one terminal)
mosquitto_sub -h 192.168.1.100 -p 1883 -u homeassistant -P YOUR-STRONG-PASSWORD -t "test/#" -v

# In another terminal, publish a test message
mosquitto_pub -h 192.168.1.100 -p 1883 -u homeassistant -P YOUR-STRONG-PASSWORD -t "test/hello" -m "world"

The subscriber terminal should print test/hello world. Mosquitto is working.

Step 4: Connect Home Assistant to Mosquitto

In Home Assistant:

  1. Settings → Devices & Services → Add Integration → MQTT
  2. Broker: 192.168.1.100
  3. Port: 1883
  4. Username: homeassistant
  5. Password: YOUR-STRONG-PASSWORD
  6. Click Submit

Home Assistant connects and the MQTT integration appears. Devices that use MQTT auto-discover and appear as entities.

For Docker Compose stacks on the same Docker network, use the container name instead of IP:

# In Home Assistant's configuration.yaml (if configuring manually):
mqtt:
  broker: mosquitto
  port: 1883
  username: homeassistant
  password: YOUR-STRONG-PASSWORD

Step 5: Deploy Zigbee2MQTT

Zigbee2MQTT bridges a Zigbee USB coordinator to MQTT — every Zigbee sensor and switch appears as an MQTT device that Home Assistant discovers automatically.

Find the Zigbee USB stick device path

ls /dev/serial/by-id/
# Example output: usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_[serial]-if00-port0

Use the stable /dev/serial/by-id/ path, not /dev/ttyUSB0 which changes on reboot.

Create Zigbee2MQTT configuration

mkdir -p ~/zigbee2mqtt/config
nano ~/zigbee2mqtt/config/configuration.yaml
homeassistant: true          # Enables Home Assistant discovery
permit_join: true            # Allow new devices to join (disable after pairing)
mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://192.168.1.100
  user: zigbee2mqtt
  password: YOUR-Z2M-PASSWORD
serial:
  port: /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_[your-serial]-if00-port0
frontend:
  port: 8080               # Zigbee2MQTT web UI
advanced:
  log_level: info
  network_key: GENERATE    # Generates a random key on first run

Add to the same Docker Compose file or a separate one

nano ~/zigbee2mqtt/docker-compose.yml
services:
  zigbee2mqtt:
    image: koenkk/zigbee2mqtt:latest
    container_name: zigbee2mqtt
    ports:
      - "8080:8080"     # Zigbee2MQTT web UI
    volumes:
      - ./config:/app/data
    devices:
      - /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_[your-serial]-if00-port0:/dev/ttyACM0
    environment:
      - TZ=America/New_York
    restart: unless-stopped
cd ~/zigbee2mqtt
docker compose up -d

Access the Zigbee2MQTT dashboard at http://192.168.1.100:8080. Put devices in pairing mode — they appear in the dashboard and automatically publish to MQTT, where Home Assistant discovers them.

Step 6: Connect Tasmota Devices

Tasmota-flashed ESP8266/ESP32 devices smart plugs, switches, sensors connect to Mosquitto via the Tasmota web UI:

  1. Open the Tasmota web interface at the device’s IP
  2. Configuration → Configure MQTT
  3. Host: 192.168.1.100
  4. Port: 1883
  5. User: homeassistant or create a dedicated user
  6. Password: your MQTT password
  7. Topic: tasmota_%06X default — includes device MAC
  8. Full Topic: %prefix%/%topic%/

Home Assistant discovers Tasmota devices automatically via MQTT discovery when the MQTT integration is connected.

Step 7: Connect WLED

WLED LED controllers support MQTT for state and control:

In WLED web UI → Config → Sync Interfaces → MQTT:

  • Enable MQTT ✓
  • Broker: 192.168.1.100
  • Port: 1883
  • Client ID: wled-[room-name]
  • User: homeassistant
  • Password: your MQTT password

WLED publishes to wled/[client-id]/ and subscribes to commands on wled/[client-id]/api/.

Monitoring MQTT Traffic

Subscribe to all topics to watch what devices are publishing:

# Watch all MQTT traffic (useful for debugging)
mosquitto_sub -h 192.168.1.100 -p 1883 \
  -u homeassistant -P YOUR-STRONG-PASSWORD \
  -t "#" -v

# Watch only Zigbee2MQTT device updates
mosquitto_sub -h 192.168.1.100 -p 1883 \
  -u homeassistant -P YOUR-STRONG-PASSWORD \
  -t "zigbee2mqtt/+/availability" -v

# Watch Home Assistant status updates
mosquitto_sub -h 192.168.1.100 -p 1883 \
  -u homeassistant -P YOUR-STRONG-PASSWORD \
  -t "homeassistant/#" -v

Adding New Users

To add a new MQTT user for a new device or service:

docker exec mosquitto mosquitto_passwd -b /mosquitto/config/password_file newuser newpassword

# Reload the password file without restarting
docker exec mosquitto mosquitto_ctl reload

To remove a user:

docker exec mosquitto mosquitto_passwd -D /mosquitto/config/password_file username
docker exec mosquitto mosquitto_ctl reload

Backing Up Mosquitto

Mosquitto’s retained messages and persistent state live in ~/mosquitto/data/. Back this up alongside Zigbee2MQTT’s config/ directory:

tar -czf ~/backup/mqtt-$(date +%Y%m%d).tar.gz \
  ~/mosquitto/config/ ~/mosquitto/data/ \
  ~/zigbee2mqtt/config/

The Zigbee2MQTT configuration.yaml and database.db contain your device pairing history — losing this means re-pairing all Zigbee devices.

Who Should Skip This Comparison

Frequently Asked Questions

What is the difference between port 1883 and 8883?

Port 1883 is standard MQTT over plain TCP — fast, zero overhead, suitable for LAN use. Port 8883 is MQTT over TLS encryption — required for sending MQTT traffic over the internet. For LAN-only setups, port 1883 with strong passwords is acceptable. Never forward port 1883 to the internet — always use a VPN or TLS.

Can Mosquitto run without a password file?

Yes — set allow_anonymous true in the config. Never do this on a network with other users or internet exposure. Anonymous access means any device on your network can publish to any topic, including spoofing sensor readings or controlling smart switches.

How many devices can one Mosquitto instance handle?

A mini PC running Mosquitto handles thousands of MQTT clients simultaneously. The typical home lab with 20-100 Zigbee devices, a dozen Tasmota plugs, and WLED strips uses under 5MB of RAM. Mosquitto is designed for constrained hardware — a mini PC runs it effortlessly at any realistic scale.

Does Zigbee2MQTT require a Zigbee coordinator stick?

Yes. Zigbee2MQTT requires a USB Zigbee coordinator: the Sonoff Zigbee 3.0 USB Dongle Plus CC2652P based, ~$20 is the current recommended option. The older CC2531 is not recommended for new setups — it lacks the processing power for large Zigbee meshes.

What is MQTT and why do I need a broker?

MQTT is a lightweight publish/subscribe messaging protocol designed for IoT devices. A broker is the central hub — devices publish sensor readings or commands to topics, and subscribers like Home Assistant receive them. Without a broker, IoT devices can’t communicate with each other or with automation platforms. Mosquitto is the standard open-source MQTT broker used in homelabs.

Do I need a separate MQTT broker if I use Home Assistant?

If you run Home Assistant OS or Supervised, the Mosquitto add-on installs in one click — no Docker setup needed. If you run Home Assistant Container plain Docker, you need a separate Mosquitto container. This guide covers the standalone Docker setup. HAOS users should install the Mosquitto add-on from the Add-on Store instead.

What IoT devices and integrations use MQTT?

Zigbee2MQTT Zigbee sensors and switches, Tasmota ESP8266/ESP32 smart plugs and switches, WLED LED controllers, Shelly devices via MQTT mode, Z-Wave JS optional, BLE2MQTT Bluetooth sensors, and many industrial/DIY sensors. MQTT is the lingua franca for DIY home automation — anything that isn’t using Zigbee’s native integration likely uses MQTT.

Is Mosquitto secure to expose to the internet?

With default settings, no — Mosquitto listens on port 1883 with no authentication. Always configure username/password authentication and never expose port 1883 to the internet. For remote MQTT access, use a VPN WireGuard or Cloudflare Tunnel to reach your broker securely. The TLS-encrypted port 8883 is for external MQTT clients when internet exposure is required.