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. The recipient is always the primary contact email stored on the client registration; API callers cannot redirect the key to another address.
5. The Technobee Service Installer blocks unless Docker, Docker Engine, and Compose v2 work.
6. The installer 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

The activation-key request contains only expiresAt. The cloud service reads the delivery address from client_registration_details.primary_contact_email.

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 Technobee Service Installer

mvn -pl cygnus-installer -am package
TECHNOBEE_INSTALLER_CONFIG=cygnus-installer/config/cygnus-installer.ini \
java -jar cygnus-installer/target/technobee-service-installer-1.0.0-SNAPSHOT.jar

This opens the Swing installation wizard. Add --cli when running on a headless server or when the terminal workflow is preferred.

Select Matrix or Cygnus using the INI product property. The INI also supplies the cloud URL, installation API base path, environment, output directory, and the product profile. No cloud URL, route, service name, or filesystem path is compiled into the installer workflow.

The installer asks for the Matrix or Cygnus Docker image and writes it to .env using the selected profile's image variable. After a successful run, review compose.yml and .env, then start with docker compose up -d. It also asks for the registry host, username, and password and performs docker login --password-stdin. The password is not stored in the generated installation package.

The installer asks for the output directory. Press Enter to accept the INI output_directory. It creates:

• compose.yml
• .env
• config/installation.yml
• config/machine-assertion.jwt
• 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 encrypted machine assertion and private key remain on premises; the cloud receives and stores only the public key. The generated service configuration records the returned client ID, installation ID/code, cloud URL, assertion path, and key paths.

The installer does not connect directly to PostgreSQL or Redis. Registration, license enforcement, and installation identity remain the selected cloud service's responsibility.

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.