Deployment¶

How Lightfall is deployed at a facility and at a beamline: which services run once per facility, which run per beamline, and exactly what must be configured today. Lightfall is in testing at the COSMIC-Scattering beamline at the ALS — a production-class deployment scoped to a single beamline while the platform matures.

Topology: facility vs. beamline¶

Most of the stack runs once per facility and is shared by every beamline:

Each beamline runs its own:

What must be configured today¶

Preferences (per installation)¶

User-facing settings live in PreferencesManager and are edited in the Preferences dialog (File → Settings). The keys below are the deployment-relevant ones, verified against src/lightfall/ui/preferences/:

IPC / NATS (ipc_settings.py):

Tiled (tiled_settings.py):

Logbook (logbook_settings.py):

Devices (device_settings.py) — backends can be enabled independently:

* The legacy single-valued device_backend key ("mock" / "bcs" / "happi") is still written for compatibility and seeds the per-backend defaults.

Connection behavior is tunable via device_instantiate_mode (default background), device_connection_timeout (default 5.0 s), and device_connect_on_startup (default true). For off-site use, the same page configures the CA tunnel (Enable CA tunnel for remote access plus a gateway address, default localhost:5099) — see Remote EPICS Access.

Authentication (YAML config)¶

The auth provider is configured in the layered YAML configuration (application.yaml), not in Preferences. Files merge in priority order: bundled package defaults → system-wide (/etc/ncs/ or %PROGRAMDATA%\ncs\) → per-user (~/.config/ncs/ or %APPDATA%\ncs\) → runtime session overrides.

auth:
  provider:
    type: keycloak        # local | keycloak | pam
    server_url: https://keycloak.example.org
    realm: alsncs
    client_id: LUCID
    redirect_uri: http://localhost:8089/callback

Field names and defaults are defined in lightfall.config.schema.AuthProviderConfig. The NCS_AUTH environment variable overrides the provider type at launch (e.g. NCS_AUTH=local for development). With no Keycloak configured, local auth and guest login keep the application usable.

Telemetry (opt-in)¶

Error reporting is disabled unless a DSN is explicitly configured — there is no default endpoint. Provide one via either:

• the SENTRY_DSN environment variable (wins), or

• the telemetry_dsn preference.

Any Sentry-compatible server works. With no DSN set, all reporting functions no-op.

Agent credentials¶

The embedded Claude agent needs Anthropic credentials on each machine: set the ANTHROPIC_API_KEY environment variable, or authenticate a Claude subscription with the Claude Code CLI (claude auth login). Everything else in the application works without it.

A minimal single-machine deployment¶

For evaluation, none of the facility services are required: install, launch, continue as guest, and use the mock device backend. Adding services is incremental from there —

1. Tiled — point tiled_url at a Tiled server; runs are cataloged and browseable. For evaluation, a stock local server works with the API-key auth mode: pip install "tiled[server]", then tiled serve catalog --temp --api-key=secret (see Your First Session).

2. NATS — point ipc_nats_url at a broker and choose a ipc_topic_prefix; external clients can now submit plans and watch runs.

3. Keycloak — configure auth.provider in YAML; logins now mint per-service API keys, and runs are access-stamped per user and ESAF.

4. Logbook server — point logbook_url at the facility logbook; local entries begin syncing.

5. Telemetry — set a DSN once an error-tracking server exists.

Preference changes for the IPC service take effect on the next restart; the service is not reconfigured at runtime.