first commit
This commit is contained in:
175
CLAUDE.md
Normal file
175
CLAUDE.md
Normal file
@@ -0,0 +1,175 @@
|
||||
# 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
|
||||
```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 exec -it mosquitto-mqtt mosquitto_passwd -b /mosquitto/config/passwords.txt USERNAME PASSWORD
|
||||
|
||||
# Delete user
|
||||
docker exec -it mosquitto-mqtt 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
|
||||
|
||||
# Publish to public topic (no auth required)
|
||||
docker exec mosquitto-mqtt mosquitto_pub -h localhost -t "public/test" -m "Hello"
|
||||
|
||||
# Publish with authentication
|
||||
docker exec mosquitto-mqtt mosquitto_pub -h localhost -t "sensors/temperature" -m "22.5" -u admin -P admin123
|
||||
|
||||
# Subscribe to all topics
|
||||
docker exec mosquitto-mqtt mosquitto_sub -h localhost -t '#' -v -u admin -P admin123
|
||||
|
||||
# Subscribe to public topics only (no auth)
|
||||
docker exec mosquitto-mqtt mosquitto_sub -h localhost -t 'public/#' -v
|
||||
|
||||
# Test Mosquitto configuration
|
||||
docker exec mosquitto-mqtt mosquitto -c /mosquitto/config/mosquitto.conf -v
|
||||
|
||||
# Access container shell
|
||||
docker exec -it mosquitto-mqtt 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
|
||||
Reference in New Issue
Block a user