PSA/ee/appliance/docs/registration-install-flow.md

Appliance registration → install flow

An on-prem appliance gets its identity before it boots: the customer registers, the alga-license control plane mints a tenant in the global registry and a one-time install code, and the appliance redeems that code at first-boot setup to come up already bound to its tenant. The ISO is generic — the install code is the only per-customer artifact.

The path a customer takes

1. Register (nm-store). The customer submits company, contact, and edition. nm-store calls alga-license POST /register-tenant, which creates the tenant_registry row, mints a one-time install code carrying the new tenant_id (plus an entitlement for paid editions), and returns a presigned, time-boxed ISO download link. The install code and link are emailed to the contact.
2. Download the generic appliance ISO from the presigned link.
3. Install. On the first-boot setup screen the operator enters the install code (and sets the admin password). The appliance redeems the code and comes up under the registry-minted tenant.
4. Reinstall (if needed). Install codes are single-use. To rebuild an appliance, re-issue a fresh code for the same tenant (below).

What happens at install (under the hood)

The host-service setup engine (ee/appliance/host-service/setup-engine.mjs, via install-code.mjs) redeems the code against ALGA_LICENSE_SERVICE_URL/register, which returns the tenant_id, the edition, and — for paid editions — the first license JWT, a per-appliance credential, and the check-in URL. Those flow into two Secrets the in-cluster bootstrap consumes:

• appliance-initial-tenant gains INITIAL_TENANT_ID. The bootstrap (helm/templates/appliance-bootstrap-configmap.yaml) runs create-tenant, which adopts that id instead of generating one, so the appliance's local tenant row is the registry tenant. (No install code → create-tenant generates a id as before; nothing else changes.)
• appliance-license-seed carries the edition + (paid) license token + connected credential/check-in URL. The bootstrap seeds license_state from it: essentials runs at the essentials tier with no token; paid is licensed from first boot and refreshes daily via check-in.

A bad, expired, or already-used code — or an unreachable license service — blocks the install with a clear message; the appliance never silently self-generates a tenant.

Re-issuing an install code (reinstall recovery)

Because codes are single-use (and consumed when the install applies them), a reinstall needs a fresh one for the same tenant. Re-issue resolves the tenant by contact email or tenant_id, revokes any still-unclaimed codes, and mints a new code + presigned link bound to the same tenant_id (re-attaching the paid entitlement). The rebuilt appliance comes back under its original identity.

Service endpoint: POST /install-codes/reissue on alga-license (service-authed), surfaced through the nm-store portal.

Operator notes

• The install code is the per-customer gate; the ISO itself is generic and not secret. The download link is presigned (registration-gated + time-boxed), not public.
• The admin password is set at install — it never travels through registration or email.
• A failed install after the code is applied needs a re-issued code (the original is already consumed).