lightscale-admin

A thin admin control plane for Lightscale. It stores operator metadata in CockroachDB and calls one or more Lightscale control plane APIs to manage networks, nodes, tokens, ACLs, key policies, and audit streams. The UI is a SPA (no SSR) and can be served by the backend or hosted separately.

Layout

• backend/: Rust (Axum) API server, /admin/api namespace.
• frontend/: Vite React SPA.

Features

Authentication

• Local account authentication
• OIDC authentication
• Session management
• Bootstrap admin creation

RBAC

• Role-based access control
• 5 default roles (Owner, Admin, Viewer, Member, Joiner)
• Membership management
• console:access permission gate for admin console/API access
• join_tokens:create permission for non-console self-service device enrollment

Control Plane Management

• CRUD operations (Create, Read, Update, Delete)
• Health check/verification

Network Management

• Create/Delete/List networks
• Node management (approve, revoke, key rotation)
• Token management (create, revoke)
• Self-service join token APIs (/admin/api/auth/join-networks, /admin/api/auth/join-token)
• ACL configuration
• Key policy configuration

Audit

• Admin audit log
• Control Plane audit log

Quick start

1. Start CockroachDB (single node for local dev):

cd /home/centra/dev/lightscale-admin

docker compose up -d

2. Create a config:

cp config.example.toml config.toml

3. Build the UI (optional if you run the Vite dev server):

cd frontend
npm install
npm run build

4. Run the backend from the repo root:

cargo run -p lightscale-admin-server

The admin UI will be served from server.static_dir if configured. Otherwise, run the Vite dev server and set server.allowed_origins to http://localhost:5173.

Configuration

Configuration loads from config.toml and LS_ADMIN__ environment variables (nested keys separated by __). See config.example.toml.

Key settings:

• server.base_url: used for OIDC redirect URLs.
• auth.bootstrap_admin_email / auth.bootstrap_admin_password: creates the first admin if the database is empty.
• server.allowed_origins: set when the UI is hosted separately (CORS + cookies).
• server.static_dir: serve the SPA from this folder (usually ../frontend/dist).
• database.disable_migration_locking: optional override to disable SQLx migration advisory locks (LS_ADMIN__DATABASE__DISABLE_MIGRATION_LOCKING=true). CockroachDB is auto-detected.

Control planes

Create control planes in the UI and store their admin tokens. The admin API will call each control plane’s /v1/* endpoints to manage networks and nodes.

Multi-region notes

CockroachDB allows multi-region deployments. For production, run a multi-node cluster and point database.url at the load-balanced SQL endpoint. The admin API itself is stateless and can be deployed across regions.