95 lines
3.7 KiB
Markdown
95 lines
3.7 KiB
Markdown
# MQTT Management Platform — Release 1
|
|
|
|
Web-based administration for an Eclipse Mosquitto 2.1 broker: management
|
|
login/RBAC, MQTT client/group/role management with ACL editing via the
|
|
Dynamic Security plugin, and generated + validated broker configuration.
|
|
|
|
Architecture and scope follow `specification.md` (Release 1, §68.1).
|
|
|
|
## Stack
|
|
|
|
```text
|
|
mqtt-frontend React (Vite build) served by nginx, proxies /api → backend
|
|
mqtt-backend FastAPI: management auth, RBAC, dynsec client, config engine
|
|
mosquitto Eclipse Mosquitto 2.1.2 (pinned), dynsec enabled
|
|
mosquitto-control control sidecar: validate/activate/reload configs
|
|
mqtt-db PostgreSQL (management data only; NOT host-exposed)
|
|
```
|
|
|
|
Networks: `frontend-net` (frontend↔backend) and `backend-net`
|
|
(backend↔db↔mosquitto↔control). Only the frontend HTTP port is published.
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
cp .env.example .env # then EDIT the change-me values!
|
|
docker compose up -d --build
|
|
```
|
|
|
|
Open http://localhost:8080 and sign in with `ADMIN_INITIAL_USERNAME` /
|
|
`ADMIN_INITIAL_PASSWORD` from your `.env`.
|
|
|
|
Bootstrap sequence on first start:
|
|
|
|
1. PostgreSQL starts; backend creates its schema (or run migrations
|
|
explicitly, see below) and seeds the management admin.
|
|
2. Mosquitto starts with `mosquitto/bootstrap/mosquitto.conf` on the
|
|
internal network; the dynsec plugin seeds its `admin` client from
|
|
`MOSQUITTO_DYNSEC_PASSWORD`.
|
|
3. Backend connects to dynsec as that admin client — the management
|
|
channel is alive.
|
|
4. Configuration changes made in the UI are generated from the
|
|
PostgreSQL model, validated with `mosquitto --test-config` (via the
|
|
control sidecar), deployed atomically, and recorded as a revision.
|
|
|
|
> **Note for Windows users:** the compose healthcheck for mosquitto and
|
|
> the control sidecar rely on Unix facilities (`pid: service:`, POSIX
|
|
> shell commands); run the stack with Docker Desktop + WSL2 as usual —
|
|
> nothing here assumes a Linux host beyond Docker itself.
|
|
|
|
## Configuration channels (why this design)
|
|
|
|
* **Dynamic Security (runtime)** — clients/groups/roles/ACLs change via
|
|
the MQTT `$CONTROL/dynamic-security/v1` API. No files involved.
|
|
* **Generated mosquitto.conf (rare)** — listeners/global settings are
|
|
generated from the DB model and deployed through `mosquitto-control`,
|
|
which shares the broker's PID namespace (`pid: "service:mosquitto"`)
|
|
to signal reloads. No Docker socket is mounted anywhere (spec §29).
|
|
* Mosquitto 2.1's HTTP API is **not** used as a management channel: it
|
|
has no authentication and (currently) exposes read-only plugin info.
|
|
|
|
## Development
|
|
|
|
Backend (in container):
|
|
|
|
```bash
|
|
docker compose exec mqtt-backend pytest -q # API + generator tests
|
|
docker compose exec mqtt-backend ruff check app tests
|
|
docker compose exec mqtt-backend alembic upgrade head # explicit migrations
|
|
```
|
|
|
|
Frontend (local dev server with proxy to backend):
|
|
|
|
```bash
|
|
cd frontend && npm install && npm run dev # http://localhost:5173
|
|
```
|
|
|
|
## Repository layout
|
|
|
|
```text
|
|
compose.yaml stack definition (5 services, 2 networks)
|
|
.env.example environment template (secrets: edit before use)
|
|
mosquitto/bootstrap/ the one file that ships with the deployment
|
|
broker-control/ validate / atomic-activate / reload sidecar
|
|
backend/ FastAPI app, models, dynsec client, configgen
|
|
frontend/ React + Vite SPA served by nginx
|
|
```
|
|
|
|
## Release 1 scope (see specification.md §68.1)
|
|
|
|
Included: management authentication & RBAC, dynsec clients/groups/roles
|
|
with the six ACL types, config generation from the PostgreSQL model,
|
|
validation, deployment with revision history.
|
|
|
|
Not yet (Release 2/3): PKI/certificates, mTLS listeners, diff view,
|
|
rollback, ACL simulator, dashboard/$SYS, audit browsing UI, backup. |