Mosquitto (MQTT)

Mosquitto is a lightweight MQTT broker. Viewu Server uses MQTT to receive Frigate events and decide which notifications to send.

This guide covers:

• A standard LAN MQTT setup (TCP 1883)
• An optional WebSockets listener (9001) for Cloudflare Tunnel usage

Quick start (most common home setup)

If you want the shortest path to “it works”:

1. Install Mosquitto (or run it via Docker)
2. Create a user/password
3. Confirm you can publish + subscribe locally
4. Point Frigate at the broker (and confirm events are flowing)
5. Deploy Viewu Server and confirm it can subscribe

If you are not using Cloudflare for MQTT, you can skip the WebSockets section.

Step 0: Prerequisites checklist

• You have a machine to run Mosquitto (often the same machine as Frigate)
• You know whether you want:
  • LAN-only access (TCP 1883), or
  • Cloudflare Tunnel access (WebSockets 9001)

Option A: Install Mosquitto on Linux (Debian/Ubuntu)

Step 1: Install

sudo apt update
sudo apt install -y mosquitto mosquitto-clients

Enable at boot and start:

sudo systemctl enable --now mosquitto
sudo systemctl status mosquitto --no-pager

Step 2: Create a user (recommended)

sudo mosquitto_passwd -c /etc/mosquitto/passwd viewu

Step 3: Configure the LAN listener (TCP 1883)

Create /etc/mosquitto/conf.d/viewu.conf:

listener 1883 0.0.0.0
allow_anonymous false
password_file /etc/mosquitto/passwd

Restart:

sudo systemctl restart mosquitto

Option B: Run Mosquitto in Docker (common if your stack is containerized)

If you already manage services with Docker Compose, this is a predictable approach.

Create a folder such as mosquitto/ and add:

compose.yml

services:
  mosquitto:
    image: eclipse-mosquitto:2
    container_name: mosquitto
    restart: unless-stopped
    ports:
      - "1883:1883"
      # Only expose 9001 if you intentionally use MQTT over WebSockets (Cloudflare)
      - "9001:9001"
    volumes:
      - ./config:/mosquitto/config
      - ./data:/mosquitto/data
      - ./log:/mosquitto/log

config/mosquitto.conf

persistence true
persistence_location /mosquitto/data/
 
log_dest stdout
 
# LAN MQTT
listener 1883
allow_anonymous false
password_file /mosquitto/config/passwd
 
# WebSockets (optional)
listener 9001
protocol websockets

Create credentials inside the container (one-time):

docker exec -it mosquitto sh -lc 'mosquitto_passwd -c /mosquitto/config/passwd viewu'
docker restart mosquitto

Tip: If you run Mosquitto as a container, remember that 127.0.0.1 means “inside the container.” Use service names (same compose network) or host LAN IPs where appropriate.

Step 4 (optional): Configure WebSockets (for Cloudflare Tunnel)

Cloudflare Tunnel supports WebSockets, but Mosquitto must listen on a WebSockets port.

If you installed on Linux via apt, create /etc/mosquitto/conf.d/websockets.conf:

listener 9001 0.0.0.0
protocol websockets
allow_anonymous false
password_file /etc/mosquitto/passwd

Restart:

sudo systemctl restart mosquitto

Common trap: Cloudflare Tunnel should forward to http://127.0.0.1:9001 (plain HTTP). Do not use HTTPS or a TCP tunnel for MQTT WebSockets.

Step 5: Test the broker (LAN)

Open terminal A:

mosquitto_sub -h 127.0.0.1 -t test/viewu -u viewu -P '<password>' -q 1

Open terminal B:

mosquitto_pub -h 127.0.0.1 -t test/viewu -u viewu -P '<password>' -m "hello" -q 1

If terminal A prints hello, authentication and basic MQTT are working.

Step 6: Confirm Frigate is publishing events

On the broker host:

mosquitto_sub -h 127.0.0.1 -t "#" -u viewu -P '<password>' -v

Then trigger an event in Frigate (walk in front of a camera). You should see messages flow.

If you see no events:

• Verify Frigate’s MQTT config (host, port, user/pass)
• Check Frigate logs for MQTT connection errors
• Confirm firewall rules allow broker access from the Frigate host

Common mistakes (and quick fixes)

• Using 127.0.0.1 from inside a Docker container (it points to the container, not the host)
• Forgetting to restart Mosquitto after changing configs
• Setting up Cloudflare MQTT using TCP instead of WebSockets
• Not actually enabling protocol websockets on the WebSockets listener