Documentation/Pluggable addons & unified SSO

Pluggable addons & unified SSO#

Luma Control ships as a focused, self-contained deployment control plane: node orchestration, image/Compose/YAML deployments, scoped secrets, deployment history, live container logs, Agent-backed resource metrics, and core alerting work out of the box with zero addons installed. 简体中文

When your cluster needs remote multi-runner Git builds, full-stack observability, or frontend product analytics and crash tracking, enable the official pluggable addons from Platform → Addons or with luma addon. Every addon shares one Luma Control identity (Passkey browser SSO and luma login CLI tokens) and auto-manages its internal secrets.

Official addons#

Addon Stack Recommended RAM & placement Auth mode
Luma Dashboard (dashboard, core required) luma-dashboard Static asset bundle under /opt/luma/dashboard (zero extra container/RAM; atomic hot-swap & rollback) Native Control session (builtin)
Luma Build (builder) luma-build >= 0.5 GiB RAM (SQLite queue; builds run on enrolled Runners; pin node recommended) Control SSO (control-sso)
Luma Observe (observe) luma-observe >= 8 GiB RAM on Manager (13 observability components; pinned to Manager) Control forwardAuth (/grafana)
Luma Eye (eye) luma-eye >= 1.5 GiB (node-edge) / 2 GiB (all-in-one); pinned node required for ClickHouse & SQLite volumes Control SSO (control-sso)

Core vs addon UI capabilities#

Luma's console adapts automatically to the addons running in your cluster (luma.addon/v1 uiCapabilities). Uninstalled addons never clutter the sidebar or expose broken panels; installing an addon unlocks its contextual extension slots immediately.

Surface Control Core (0 addons) Unlocked by Luma Build Unlocked by Luma Observe Unlocked by Luma Eye
Sidebar monitoring Monitoring (4 native views): Incidents, Metrics, Rules, Channels — Expands to Observability: adds Platform health, App monitoring (Grafana/logs/traces), Dashboard sharing Adds Frontend RUM (/observe/eye) portfolio summary
Deployments & Create Deployment timeline, image/YAML/template creation Unlocks Git repository import (/builds), remote build retries, and Builder console link — —
Application Detail Overview, Services, Alerts, Live Logs, Metrics, Config, Secrets, Versions — Adds overview pipeline status, Dashboards tab (Grafana + task board), historical log search & Tempo traces in Logs, Alertmanager alerts Adds Frontend (eye) tab on applications matched to an Eye project by slug or domain
Alert rule presets 7 native Agent/Control presets (node.*, app.memory, task.queue_age) Adds build.failed Adds 11 HTTP, Nomad, log-match, and Taskiq/Celery presets —

Unified Control authentication#

Luma Control acts as the single Identity Provider (IdP) for all addons:

  1. Browser SSO (control-sso, used by Luma Build and Luma Eye): opening an addon console redirects to https://<control-domain>/dashboard/addon-login?addon=<id>&challenge=..., reuses your existing Passkey/dashboard session, issues a one-use PKCE ticket, and establishes an audience-bound opaque addon session (las_...). Signing out of Control or uninstalling the addon revokes all addon sessions immediately.
  2. ForwardAuth (forward-auth, used by Luma Observe): Traefik verifies /grafana requests against Control's /v1/auth/forward endpoint using the same dashboard session or management token.
  3. Zero-extra-token CLI & automatic URL discovery: both luma builder and luma eye automatically reuse your active luma login token and discover the deployed addon URL directly from Control (no manual endpoint setup required). When targeting a separately hosted Builder or overriding the discovered endpoint, pass --url, set LUMA_BUILD_URL, or bind once with luma builder use <url>.
luma addon list
luma builder status
luma eye status
luma eye portfolio --since 24h

First-time configuration & secret automation#

You never need to hand-edit YAML files or manually invent internal tokens when installing an addon:

Installing, configuring and uninstalling#

One-click install from the browser#

Open Platform → Addons, click Install on any official addon, verify the pre-selected pinned node and live memory precheck, fill in the domain (if not pre-filled), and click Save & install. Control pulls the official prebuilt GHCR images declared in the addon spec and deploys the stack in place.

Installing via CLI#

# One-click install using official prebuilt GHCR images
luma addon install eye --domain eye.example.com --region cn --node manager --yes
luma addon install observe --region cn --yes
luma addon install builder --domain build.example.com --use-registry ghcr.io --use-git-provider github:my-account --yes

For dedicated public-IP telemetry nodes (node-edge preset on Luma Eye), pass --preset node-edge --node <edge-node>:

luma addon install eye --preset node-edge --domain eye.example.com --region global --node edge-1 --yes

Building from local source (for development or custom forks)#

Pass --source <dir> to build and push images locally before deploying through the same addon configuration pipeline:

luma addon install eye --source ./eye --yes
luma addon install builder --source ./builder --yes
luma addon install observe --source ./observe --yes

Updating settings or uninstalling safely#

luma addon show eye
luma addon configure eye --set retentionDays=14 --apply
luma addon uninstall eye

Uninstalling stops the addon services and routes, revokes its Control SSO sessions, and immediately hides its UI extension slots in the console. Persistent data volumes (eye-data, clickhouse-data, luma-build-data) are preserved by default unless --delete-storage is explicitly passed.

Hot-swapping the Dashboard without rebuilding Control#

Luma Dashboard is managed as a required core static-bundle addon stored under /opt/luma/dashboard with atomic symlink switching and instant rollback. Frontend UI updates never require rebuilding or restarting luma-control:

# Pull latest published dashboard bundle from GitHub Releases (or configured mirror)
luma addon install dashboard

# Build locally from dashboard-src and upload directly (zero Docker build)
luma addon install dashboard --source ./dashboard-src

# Instant rollback to the previous dashboard bundle
luma addon rollback dashboard

Declarative luma.addon/v1 specification#

Official addons live under luma/assets/addons/*.yaml (dashboard.yaml, builder.yaml, eye.yaml, observe.yaml). Each manifest declares its kind (compose or static-bundle), auth contract, uiCapabilities, requirements (minimum/recommended RAM and stateful node-pinning policy), defaultImages or bundle URLs, topology presets, tiered configSchema (basic, recommended, advanced), and autoSecrets. External extensions can adopt the exact same schema to participate in Control SSO and schema-driven configuration.