174 lines
6.4 KiB
Markdown
174 lines
6.4 KiB
Markdown
# 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 read-only access to `public/#` and `$SYS/#` topics (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)
|
|
- `config/passwords.txt.template`: Tracked placeholder copied to `passwords.txt` on bootstrap
|
|
- `.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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# Add/update user password
|
|
docker compose exec -T mosquitto mosquitto_passwd -b /mosquitto/config/passwords.txt USERNAME PASSWORD
|
|
|
|
# Delete user
|
|
docker compose exec -T mosquitto mosquitto_passwd -D /mosquitto/config/passwords.txt USERNAME
|
|
|
|
# After modifying users or ACL, restart Mosquitto
|
|
docker compose restart mosquitto
|
|
```
|
|
|
|
### Testing & Debugging
|
|
```bash
|
|
# Run test script (sends sample messages to various topics)
|
|
./test-mqtt.sh
|
|
|
|
# Subscribe to public topic (no auth required)
|
|
docker compose exec -T mosquitto mosquitto_sub -h localhost -t "public/#" -v
|
|
|
|
# Publish with authentication
|
|
docker compose exec -T mosquitto mosquitto_pub -h localhost -t "sensors/temperature" -m "22.5" -u admin -P $MQTT_ADMIN_PASSWORD
|
|
|
|
# Subscribe to all topics
|
|
docker compose exec -T mosquitto mosquitto_sub -h localhost -t '#' -v -u admin -P $MQTT_ADMIN_PASSWORD
|
|
|
|
# Test Mosquitto configuration
|
|
docker compose exec -T mosquitto mosquitto -c /mosquitto/config/mosquitto.conf -v
|
|
|
|
# Access container shell
|
|
docker compose exec -it mosquitto sh
|
|
docker compose 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 read-only `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
|
|
- config/passwords.txt should be readable by the mosquitto user (chmod 640)
|
|
|
|
### 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 read-only public/* topics
|