patcharp/centrifugo-admin repository overview

⁠Centrifugo Admin UI

Next.js admin console for Centrifugo⁠ v6 with monitoring comparable to the AWS IoT MQTT console — dashboard, channel explorer with live tail, connections view, message search, and audit log.

⁠Features

• Dashboard — live node metrics (connections, channels, publish rate) streamed over SSE
• Channel explorer — browse active channels, inspect presence/history, live-tail messages, publish test messages
• Connections — live event feed of messages flowing through the broker
• Message search — full-text search over the ClickHouse message archive
• Users & audit — local admin accounts (SQLite) with an audit trail of every admin action
• No standing channel subscriptions: the admin is a pure observer and only opens connections on demand (e.g. live tail sessions)

⁠Architecture

The image contains only the admin UI. A full deployment needs:

⁠Quick start (docker compose)

services:
  admin:
    image: patcharp/centrifugo-admin:0.1.0
    ports:
      - "3000:3000"
    environment:
      - AUTH_SECRET=${AUTH_SECRET}                        # 32-byte random secret for session JWTs
      - SQLITE_PATH=/app/data/admin.db
      - CENTRIFUGO_API_URL=http://centrifugo:8000/api
      - CENTRIFUGO_API_KEY=${CENTRIFUGO_API_KEY}          # must match Centrifugo http_api.key
      - CENTRIFUGO_WS_URL=ws://centrifugo:8000/connection/websocket
      - CENTRIFUGO_HMAC_SECRET=${CENTRIFUGO_HMAC_SECRET}  # must match Centrifugo client token secret
      - CLICKHOUSE_URL=http://clickhouse:8123
      - CLICKHOUSE_DB=admin
      - INGEST_API_KEY=${INGEST_API_KEY}                  # optional, see "Message archiving"
    volumes:
      - admin-data:/app/data

volumes:
  admin-data:

Then create the first admin account:

curl -X POST http://localhost:3000/api/auth/register \
  -H 'content-type: application/json' \
  -d '{"username":"admin","password":"<strong-password>"}'

and sign in at http://localhost:3000.

⁠Environment variables

⁠Message archiving

The admin never subscribes to channels by itself. Messages reach the archive (and the live events feed) two ways:

1. Published through the admin UI (/api/centrifugo/publish / broadcast) — archived automatically.
2. Published directly to Centrifugo by your backend — mirror each message to the admin:

curl -X POST http://admin:3000/api/ingest \
  -H 'content-type: application/json' \
  -H "x-api-key: $INGEST_API_KEY" \
  -d '{"channel":"chat:room1","payload":{"text":"hello"},"user":"u1","protocol":"api"}'

Only channel is required. The endpoint returns HTTP 500 when the ClickHouse insert fails, so callers can safely retry. (Centrifugo OSS has no outbound per-publish webhook — proxies only fire for client-side publishes — hence the mirror pattern.)

⁠Health check

GET /api/health is unauthenticated and suitable for container health checks:

healthcheck:
  test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/api/health').then(r => { if (!r.ok) process.exit(1) })"]
  interval: 10s

⁠Tags

• 0.1.1, latest — linux/amd64 (branded favicon fix)
• 0.1.0 — linux/amd64