mosquitto-mqtt-broker/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Docker-based MQTT server setup using Eclipse Mosquitto broker with a web-based MQTTUI dashboard. The system provides MQTT messaging on port 1883, WebSocket support on port 9001, and a web dashboard on port 5000.

Architecture

Container Stack

• mosquitto: Eclipse Mosquitto MQTT broker (eclipse-mosquitto:2)

  • Runs with user-specified UID/GID from .env
  • Two listeners: MQTT (1883) and WebSocket (9001)
  • Persistence enabled with data stored in ./data/mosquitto.db

• mqttui: Web dashboard (terdia07/mqttui:latest)

  • Depends on mosquitto service
  • Database-enabled for message storage (SQLite)
  • Configurable via environment variables
  • Stores data in ./mqttui-data/ directory

Authentication & Authorization

• Dual authentication model: Supports both anonymous and authenticated users
• Anonymous users have limited access to public/# and $SYS/# topics only (defined in config/acl.conf:6-10)
• Authenticated users require username/password stored in config/passwords.txt
• Six user types defined (config/acl.conf):
  • admin/joachim: Full access (readwrite #)
  • panel: Dashboard user with full access
  • testuser: Personal topic access (user/testuser/#) + public topics
  • device1/device2: Device-specific write access (devices/deviceX/#) with read-only status
  • monitor: Global read-only access

Configuration Files

• config/mosquitto.conf: Main broker configuration (listeners, persistence, auth, logging)
• config/acl.conf: Access Control Lists defining per-user topic permissions
• config/passwords.txt: Generated by setup.sh, stores hashed passwords (not in repo)
• .env: Environment variables for credentials and settings (not in repo, use .env.example)
• mqtt-panel-config.json: Legacy config file (current setup uses mqttui instead of mqtt-panel)

Development Commands

Initial Setup

# Copy environment template and configure credentials
cp .env.example .env
# Edit .env and set all passwords

# Make scripts executable
chmod +x setup.sh test-mqtt.sh

# Start containers
docker-compose up -d

# Create MQTT users from .env credentials
./setup.sh

Container Management

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f                    # All services
docker-compose logs -f mosquitto          # Mosquitto only
docker-compose logs -f mqttui             # MQTTUI only

# Restart services
docker-compose restart                    # All
docker-compose restart mosquitto          # Mosquitto only

# Stop and remove containers
docker-compose down

# Stop and remove including volumes
docker-compose down -v

User Management

# Add/update user password
docker exec -it mosquitto mosquitto_passwd -b /mosquitto/config/passwords.txt USERNAME PASSWORD

# Delete user
docker exec -it mosquitto mosquitto_passwd -D /mosquitto/config/passwords.txt USERNAME

# After modifying users or ACL, restart Mosquitto
docker-compose restart mosquitto

Testing & Debugging

# Run test script (sends sample messages to various topics)
./test-mqtt.sh

# Publish to public topic (no auth required)
docker exec mosquitto mosquitto_pub -h localhost -t "public/test" -m "Hello"

# Publish with authentication
docker exec mosquitto mosquitto_pub -h localhost -t "sensors/temperature" -m "22.5" -u admin -P admin123

# Subscribe to all topics
docker exec mosquitto mosquitto_sub -h localhost -t '#' -v -u admin -P admin123

# Subscribe to public topics only (no auth)
docker exec mosquitto mosquitto_sub -h localhost -t 'public/#' -v

# Test Mosquitto configuration
docker exec mosquitto mosquitto -c /mosquitto/config/mosquitto.conf -v

# Access container shell
docker exec -it mosquitto sh
docker exec -it mqttui sh

Important Notes

Security Considerations

• .env file contains all credentials and MUST NOT be committed (already in .gitignore)
• Default passwords in .env.example must be changed for production
• Anonymous access is enabled but restricted to public/# topics via ACL
• All credentials are loaded from .env by setup.sh (lines setup.sh:8-18)
• The SECRET_KEY in .env is used by mqttui for session management

ACL Behavior

• ACL rules are evaluated per-user (config/acl.conf)
• Anonymous users get explicit rules defined under user anonymous
• Authenticated users inherit their specific user rules
• Pattern # is wildcard for all topics, + for single-level wildcard
• After ACL changes, always restart mosquitto: docker-compose restart mosquitto

MQTTUI Dashboard

• The docker-compose.yml uses mqttui (not mqtt-panel as mentioned in README.md)
• Dashboard connects to broker using credentials from .env: MQTT_PANEL_USERNAME/PASSWORD
• Database storage enabled (DB_PATH=/app/data/mqtt_messages.db) with cleanup after 30 days
• Max 10,000 messages retained in database (DB_MAX_MESSAGES)
• Widget configuration is managed through mqttui web interface, not mqtt-panel-config.json

File Permissions

• Mosquitto runs as UID:GID specified in .env (default 1000:1000)
• Ensure config/, data/, and log/ directories have correct permissions
• passwords.txt should be readable by the mosquitto user (chmod 644)

Persistence

• MQTT messages persist in ./data/mosquitto.db
• MQTTUI data stored in ./mqttui-data/mqtt_messages.db
• To completely reset: docker-compose down -v and remove data/log directories

Endpoints

• MQTT: localhost:1883
• WebSocket: ws://localhost:9001
• Web Dashboard: http://localhost:5000

Common Patterns

Adding a New User Type

1. Add credentials to .env
2. Update setup.sh to create the user (lines setup.sh:59-86)
3. Add ACL rules in config/acl.conf
4. Run ./setup.sh to create user
5. Restart mosquitto: docker-compose restart mosquitto

Debugging ACL Issues

1. Enable verbose logging in config/mosquitto.conf (add log_type all)
2. Restart mosquitto: docker-compose restart mosquitto
3. Check logs: docker-compose logs -f mosquitto
4. Look for "DENIED" messages indicating ACL blocks

Client Integration

• Use MQTT port 1883 for native MQTT clients (Python paho-mqtt, etc.)
• Use WebSocket port 9001 for browser-based clients
• Provide username/password from .env for authenticated topics
• Use anonymous connection only for public/* topics