Skip to main content

Installation

Installation is the tenant-side half of the pipeline: it turns a published, signed version into an active installation with negotiated capabilities, registered workflows and a renderable UI bundle.

Install paths​

Two equivalent paths exist:

  • Portal wizard — Solutions → Marketplace → Install. The wizard shows the manifest, requested vs granted capabilities, required connectors and settings before activation.
  • CLI — for automation and testing:
qefro solution install restaurant-pro

The CLI sends the tenant and organization context headers with the install request, mirroring the portal's identity.

The activation pipeline​

Each step fails the whole installation atomically — a partially installed solution is never exposed to the tenant.

StepWhat happensFailure mode
ResolveRegistry resolves the exact version and connector constraintsUnknown version / unresolvable connector version
VerifySignature over id|version|checksum is re-verifiedTampered or unsigned package
NegotiateGranted set = requested capabilities ∩ grantable permissionsCapability requires a missing manifest permission
ConnectorsTenant connectors enabled; shared pool instances ensuredConnector not published / pool unhealthy
SecretsTenant credentials stored AES-256-GCM encryptedMissing required credential
RegisterWorkflows and prompts registered with the runtimeInvalid workflow definition
UI bundleParsed UI stored per version; register ui activation stepPublish-time validation already covers this

Capability negotiation​

The manifest's permissions and the UI's requested capabilities are intersected with what the installation grants:

For [email protected], requesting workflow.trigger and storage.* with matching permissions grants those capabilities (SDK ctx.storage). connector.invoke is not granted when connectors: []. Own-app UI sources use runtime.query. The granted set is re-checked on every host call — it is not a one-time handshake. Reference: Capabilities.

Settings​

Manifest settings declare tenant-configurable values (see Manifest). At install time the tenant provides values for required settings; defaults apply otherwise. Settings are stored tenant-scoped and are merged on upgrade — see below.

caution

Settings updates merge; keys are not removed automatically. Design setting keys to be stable across versions.

Upgrade​

qefro solution install restaurant-pro   # resolves the latest published version

Upgrading replaces the installed version's workflows, prompts and UI bundle with the new version's. Version data is persisted per version, so uninstall and rollback drop exactly what the version introduced.

Notes:

  • Published versions are immutable — an upgrade always moves forward to a new version.
  • Connector constraints are re-resolved; a constraint the registry can no longer satisfy blocks the upgrade.
  • Capabilities are re-negotiated for the new version; the wizard displays any change to the granted set.

Uninstall​

Uninstalling a solution:

  • deregisters its workflows and prompts from the runtime,
  • drops the UI bundle and version-scoped definitions,
  • disables tenant connectors that no other installation needs,
  • leaves the shared connector pool running for other tenants.

Connector credentials are removed from the secret manager when no installation references them.

Verifying an installation​

qefro solution list

lists installed solutions with version and status for the tenant context. In the portal, the installation card shows the granted capabilities, declared connectors and active version.