Skip to content
brūhi Docs

Authentication & Setup

brūhi Cloud includes a streamlined first-run setup wizard, license activation workflow, and role-aware session management for multi-DJ radio operations.

Initial Owner Setup

Section titled “Initial Owner Setup”

When launching brūhi Cloud for the first time, accessing the web dashboard (/) triggers the initial setup wizard if no owner user has been configured yet:

First Launch
     ↓
Owner Account Creation (Email + Password / Auth Setup)
     ↓
Redirect to Admin Panel (/admin)
     ↓
License Activation & Default Station Auto-Creation
     ↓
Dashboard (Station Workspace)
  1. Owner Registration: The system prompts for initial administrator/owner credentials, or auto-seeds the owner account on startup if BRUHI_ADMIN_EMAIL and BRUHI_ADMIN_PASSWORD are set in .env.
  2. WebAuthn / Passkeys Setup: Operators can register biometric passkeys (TouchID, FaceID, YubiKey) bound to the domain configured in BRUHI_RP_ID (e.g. radio.yourdomain.com).
  3. License Activation: Upon owner creation, the app redirects to /admin for license key entry and validation against Lemon Squeezy.
  4. Station Auto-Creation: Activating a valid license automatically initializes default Station 1 (in bundled Icecast mode) and configures its default parameters.
  5. Session Auto-Selection: After license activation, the default station is automatically assigned and selected for your active broadcast session.

Station Selection & Persistence

Section titled “Station Selection & Persistence”

For subsequent logins or multi-station environments:

  • The user logs in and is presented with station cards displaying:
    • Station name and station number
    • On-air broadcast status
    • Active listener metrics
  • Active station selection is persisted in browser local storage and server session state (sessionStore).
  • Switching active stations dynamically rebinds live controls, studio lock states, and playout feeds to the selected station.

Studio Session Locks

Section titled “Studio Session Locks”

To prevent conflicting controls when multiple DJs or administrators access the system simultaneously:

  • Station Controller Locks: brūhi Cloud implements server-side session locking (server/studio_session).
  • When a DJ initiates live broadcasting or takes control of a station, a session lock is claimed.
  • Other connected clients receive lock notifications and enter read-only preview mode until the lock is released or handed off.

API Security & Token Validation

Section titled “API Security & Token Validation”

The REST API enforces secure token validation and request header checks:

  • Insecure Default Credentials Removed: All default development passwords and hardcoded keys have been eliminated.
  • API Token Validation: Administrative and control endpoints require an explicit authorization token passed via request headers (Authorization: Bearer <API_TOKEN>).
  • Environment Token Config: Set API_TOKEN in your .env configuration file for backend services, automated scripts, and external integrations.