Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sonicverse.eu/llms.txt

Use this file to discover all available pages before exploring further.

The status panel is an optional component with two parts: a Flask API backend (status-api) inside the Docker stack, and a Next.js frontend (dashboard) for deployment on Appwrite Sites. The API is disabled by default — enable it explicitly to use the panel.

​
Enabling the status panel

Set ENABLE_STATUS_PANEL=1 in your .env file to include the status API service. The interactive installer asks whether you want to enable it during setup. If you manage the stack with docker compose directly instead of the installer, start it with the status-panel profile: 
docker compose --profile status-panel up -d
When the status panel is disabled (the default), nginx automatically removes the /api/ proxy routes from its configuration at startup. No API endpoints are exposed.
Existing deployments that already use the status panel need to add ENABLE_STATUS_PANEL=1 to their .env file after upgrading. Without it, the status API service will not start and /api/ routes will return a 404.

​
Features

  • Live listener counts and mount point status (5-second refresh)
  • Container health monitoring
  • Stack configuration overview
  • Recent alerts timeline
  • Emergency audio upload and management
  • Role-based write access via Appwrite teams

​
Branded root page

Nginx serves a styled HTML status page at your server’s root URL (/). The page displays your station name, available stream endpoints with SVG icons, and admin contact information. The endpoint grid uses a two-column layout on desktop and single-column on mobile. The page includes a noindex, nofollow meta tag to prevent search engine indexing. The page is generated automatically at container startup from two environment variables:
VariableDescriptionDefault
STATION_NAMEStation name shown on the pageMy Radio Station
STATION_ADMIN_EMAILContact email shown on the pageadmin@example.com
No manual configuration is needed if you already set these values in your .env file — the root page picks them up automatically. See configuration for all station variables.

​
API backend

When enabled, the API backend runs as a Docker container in the stack and is proxied through Nginx at /api/. It provides endpoints for:
  • Stream health and listener statistics
  • Docker container status
  • Emergency audio file management (upload, list, delete)
  • Stack configuration details

​
HTTPS enforcement

Operator endpoints (/api/ and /icecast-admin/) require HTTPS. HTTP requests to these paths are automatically redirected with a 308 Permanent Redirect. Public media endpoints (/hls/, /listen/) remain available on HTTP for player compatibility.

​
Alert ingestion

The /api/alert endpoint accepts alerts from the analytics service and Liquidsoap. This endpoint is restricted at the Nginx level to private and loopback IP addresses only (Docker bridge networks, 127.0.0.1, ::1). External requests receive a 403 Forbidden response. No configuration is needed — the restriction applies automatically.

​
Dashboard deployment

The frontend is a Next.js application in the apps/dashboard/ directory. It includes Sonicverse branding in the header and login form, and a footer with copyright, license, and documentation links.
1

Configure environment

cd apps/dashboard
cp .env.local.example .env.local
Edit .env.local with your streaming server URL and Appwrite credentials.
2

Build

npm install && npm run build
3

Deploy

Deploy the out/ directory to Appwrite Sites or any static hosting provider.

​
Authentication

The status panel uses Appwrite team-based authentication. Only members of the configured Appwrite team can access the dashboard. APPWRITE_TEAM_ID is required whenever APPWRITE_PROJECT_ID is set — the panel will not authenticate users without it. Write operations (managing emergency audio, restarting services) require a role listed in STATUS_PANEL_WRITE_ROLES. This defaults to owner,admin.
VariableDescriptionDefault
ENABLE_STATUS_PANELSet to 1 to run the status API and expose /api/ through nginx0
APPWRITE_ENDPOINTAppwrite API endpoint—
APPWRITE_PROJECT_IDAppwrite project ID—
APPWRITE_TEAM_IDTeam ID (required when APPWRITE_PROJECT_ID is set) — only members get access—
STATUS_PANEL_CORS_ORIGINDashboard URL(s) for CORS, comma-separated—
STATUS_PANEL_HOSTBind host for the API server (auto-detects container IP in Docker)127.0.0.1
STATUS_PANEL_WRITE_ROLESRoles allowed to manage emergency audioowner,admin

​
Remote commands

When STATUS_PANEL_ALLOW_RISKY_COMMANDS is set to 1, the dashboard can trigger:
  • Docker container restarts
  • SSL certificate renewal
Only enable this on trusted networks. These commands allow remote control of your Docker stack.