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:
- Browser SSO (
control-sso, used by Luma Build and Luma Eye): opening an addon console redirects tohttps://<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. - ForwardAuth (
forward-auth, used by Luma Observe): Traefik verifies/grafanarequests against Control's/v1/auth/forwardendpoint using the same dashboard session or management token. - Zero-extra-token CLI & automatic URL discovery: both
luma builderandluma eyeautomatically reuse your activeluma logintoken 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, setLUMA_BUILD_URL, or bind once withluma 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:
- Auto-managed by Control (zero setup):
LUMA_CONTROL_URL(andLUMA_DEPLOY_TOKENforbuilder) are wired automatically.- Internal secrets (
LUMA_EYE_ADMIN_TOKEN,LUMA_EYE_RELAY_SECRET,LUMA_EYE_AUTO_KEY,LUMA_OBSERVE_READ_TOKEN,LUMA_OBSERVE_INGEST_TOKEN) are generated cryptographically on first configure and preserved across upgrades unless--rotate-secretsis passed. LUMA_EYE_AUTO_ORIGIN_SUFFIXESis derived automatically from your Eye domain (for exampleeye.example.com→.example.com,localhost,127.0.0.1).- Credential reuse (zero duplicate entry):
- When configuring Luma Build in Addons Hub or via CLI, select an already-saved Control container registry or Git provider instead of retyping passwords or PATs.
- Minimal required inputs & live prechecks:
- Luma Eye: 1 domain + region + mandatory pinned node (auto-selected when the target region has 1 node; best candidate pre-selected when multiple nodes exist).
- Luma Observe: 1 Manager region (auto-detected from the registered Manager node).
- Luma Build: 1 domain + registry (inherited from Control when available) + recommended pinned node.
- Before deploying, the install dialog checks the target node's real available and total RAM against the addon's
requirementsand warns clearly if memory is tight or insufficient. - After installing Luma Build, if 0 build runners are online, both Addons Hub and Build from Git show an inline runner enrollment guide (
luma builder token create+luma runner join).
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.