Admin Dashboard

Monitor system health, manage users, and configure the server.

The Admin Dashboard is a web-based control panel accessible only to users with the admin role. It provides a unified interface for monitoring server health, managing users, inspecting logs, controlling tile sets, and managing operational data. Access it at /admin from any connected browser.

System Status

The Status tab presents an auto-refreshing overview of server health. Metrics are polled every 5 seconds via GET /api/admin/status and pushed in real time via the Socket.IO admin:status event.

The detailed health endpoint at GET /api/health/detailed exposes the same telemetry as structured JSON, optionally protected by an API key set in HEALTH_API_KEY. This endpoint is suitable for external monitoring integration.

Connected Clients

The Clients tab shows an enriched view of every active Socket.IO connection. Unlike the simple count on the Status tab, this view exposes per-connection metadata:

• Callsign — the user's registered display name
• Role — current role badge (observer / operator / admin)
• Connect time — ISO timestamp when the connection was established
• Duration — how long the connection has been active
• User agent — browser and OS string from the initial HTTP handshake
• Last position — coordinates and timestamp of the most recent GPS update

An Online Only toggle filters the list to currently connected users, hiding accounts that have disconnected since the page loaded. The list updates in real time as users connect and disconnect.

User Management

The Users tab lists all registered accounts with their current role and connection status. Admins can perform the following actions on any account other than their own:

Role Assignment

Change a user's role via the role dropdown. The change is applied immediately via PUT /api/users/:id/role and takes effect on the user's next Socket.IO event — no reconnect required. Demoting an operator to observer instantly restricts their ability to send messages or create markers.

Disable and Enable Accounts

Disabling an account blocks the user from logging in and prevents Socket.IO re-authentication. Any existing JWT the user holds remains cryptographically valid until it expires, but re-authentication after token expiry will be blocked. Use a short JWT_EXPIRY in security-sensitive deployments.

Password Reset

Admins can generate a temporary password for any account. The temporary password is displayed once in the dashboard — copy and deliver it to the user through a side channel. The user should change it immediately after logging in.

Log Viewer

The Logs tab provides direct access to the server's structured log stream from the browser. Logs are captured by a Pino ring buffer holding the most recent 1,000 entries in memory and streamed in real time via Socket.IO.

Controls available in the log viewer:

• Level filter — show only error, warn, info, or debug entries and above
• Text search — filter entries by substring match on the log message
• Auto-scroll — toggle whether the view scrolls to the latest entry as new logs arrive
• Clear display — clears the visible log list without affecting the server-side ring buffer

Tile Management

The Tiles tab exposes server-side tile set management without requiring SSH or direct filesystem access. It reuses the same tile services that back the setup wizard.

• List tile files — shows all .pmtiles and .mbtiles archives in the tiles volume, with file size and last-modified date
• Download by location — trigger a server-side tile download for a named location; the server geocodes the location and downloads tiles for a computed bounding box and zoom range
• Download by bbox — specify a custom bounding box (min/max lat/lon) and zoom range for targeted downloads
• Import MBTiles or PMTiles — upload a locally prepared tile archive file to the server's tile volume
• Set active tileset — select which archive TileServer GL should serve to clients; the active tileset is persisted across restarts
• Delete tile file — remove an archive from disk; confirmation required; the active tileset cannot be deleted

Data Management

The Data tab shows current record counts for each data type and provides bulk-delete operations for purging operational data. All destructive operations require explicit confirmation before execution.

Feature Toggles

GroundWave supports selective feature enablement via the FEATURES_ENABLED environment variable. This allows operators to run a minimal deployment with only the subsystems required for the mission.

# Enable only chat and position tracking (no markers, files, or overlays)
FEATURES_ENABLED=chat

# Enable all features (default behavior when variable is unset)
FEATURES_ENABLED=chat,markers,files,overlays,voice,federation

Supported feature keys:

When a feature is disabled, the corresponding REST endpoints return 404, Socket.IO events for that feature are silently dropped, and the client conditionally hides the associated UI elements. Position tracking is always enabled and cannot be toggled off.