matrix/docs/client-registration-installation-runbook.md

Client registration and controlled installation runbook

Lifecycle

1. An administrator creates one legal registration.
2. One or more tenant accounts are attached to that registration.
3. A time-bound license defines package, user, and installation limits.
4. An activation key is generated, stored only as a BCrypt hash, and emailed.
5. The Java wizard blocks unless Docker, Docker Engine, and Compose v2 work.
6. The wizard validates the key, generates an RSA-3072 installation key, and registers the installation in one database transaction.
7. The plaintext activation key is neither returned again nor written locally.
8. Runtime token issuance requires an active registration, tenant, license, and installation.
9. An administrator can decommission or revoke an old installation before activating its replacement.

Database migration

Apply 004_client_registration_activation.sql after identity migrations 001–003. The migration is additive and idempotent. Always back up production before applying it and validate the constraints on a staging copy first.

Required cloud configuration

• Database and Redis variables already used by the cloud service
• JWT and assertion encryption key locations
• CYGNUS_MAIL_HOST, CYGNUS_MAIL_PORT, CYGNUS_MAIL_USERNAME, CYGNUS_MAIL_PASSWORD, and CYGNUS_REGISTRATION_EMAIL_FROM
• Optional CYGNUS_ACTIVATION_MAX_ATTEMPTS and CYGNUS_ACTIVATION_RATE_WINDOW

The cloud service can start without SMTP, but the activation-key email endpoint will reject delivery until SMTP is configured.

Administrative API order

All administration endpoints require an access token with cygnus.admin scope.

1. POST /api/v1/admin/client-registrations
2. POST /api/v1/admin/client-registrations/{registrationId}/tenants
3. POST /api/v1/admin/tenants/{tenantId}/licenses
4. POST /api/v1/admin/tenants/{tenantId}/licenses/{licenseId}/activation-key

For replacements:

• POST /api/v1/admin/tenants/{tenantId}/installations/{id}/decommission
• POST /api/v1/admin/tenants/{tenantId}/installations/{id}/revoke

Both require a non-empty reason, invalidate the cached installation, increment its security version, and write an audit event.

Running the wizard

mvn -pl cygnus-installer -am package
CYGNUS_CLOUD_URL=https://cloud.example.com \
java -jar cygnus-installer/target/cygnus-installer-1.0.0-SNAPSHOT.jar

After a successful run, review the generated compose.yml, set CYGNUS_IMAGE, and start with docker compose up -d.

The wizard asks for the output directory. Press Enter to accept CYGNUS_INSTALL_OUTPUT, which defaults to ./cygnus-installation. It creates:

• compose.yml
• config/installation.yml
• config/keys/client-signing-private.pem
• config/keys/client-signing-public.pem

The generated private key must remain readable only by the service account. Never email or copy it to the cloud. The cloud stores only its public key.

Operational checks

• Alert on repeated HTTP 429 activation responses.
• Alert on failed SMTP delivery and keep activation-key issue events auditable.
• Review installations that have stale last_seen_at.
• Revoke suspected keys/installations immediately.
• Do not increase max_installations to recover a failed server. Decommission the old installation with a reason, then activate the replacement.
• Back up registration, tenant, license, installation, activation-key, session, and installation-audit tables together.