Control sources for Workspace Sites

Workspace installs a Site as a complete, editable Sitegenerator project. Installation does not create a live release or publish content. Build and publication remain separate, explicit steps.

Choose a source mode

The installation-wide setting cms.site_packages.source_mode supports three modes:

Use store_only for a hosted environment. Tenants cannot relax this installation-wide policy. Configure trusted catalog Ed25519 keys in cms.site_packages.store_trusted_public_keys; never place private signing keys in Workspace configuration.

The Store URL may contain a fixed service path. The central schukai catalog uses https://www.schukai.com/apps/workspace/sites. Redirects, descriptors, and archives must remain below that path. A URL on the same host but outside the configured path is treated as an external source. The hosted solution keeps store_only locked so a tenant cannot enable arbitrary sources.

Install a Site

In the public catalog, select Install in Workspace and enter the base URL of your Workspace. After signing in, choose the empty target Site under Sites. Its Sites catalog opens with the selected template highlighted. Installation starts only after you review and confirm the plan.

This direct route applies to free versions. For paid versions, the Commerce store starts installation from the customer account; the standalone Site Package catalog only marks them as paid purchases.

Create an empty Site, start a development session, open the Sites tab, and select a published version. Review the plan before confirming it. Existing files, releases, or missing capabilities block installation. Build and publish your own release only after reviewing the editable source.

The installed copy is independent from the template. Automatic package upgrades are not part of the first version.

For a paid Site, the customer account creates a short-lived installation grant only after payment coverage has been confirmed. The browser passes it directly to the selected Workspace Site. The grant never enters the URL or browser storage and is bound to the purchase, target Site, and package version. A later refund can block new installations and downloads; installed sources and the historical supply evidence remain unchanged.

Use nucli

Site Package V2 can include product snippets, document templates, transactional mail templates, logos, fonts and brand themes. Installation uses the existing document and notification processes; it neither creates invoices or shipments nor sends mail.

V3 adds legacy logo resources, custom HTML footer templates, and bindings for multiple notification and document profiles. The server must support sitepackage.theme-components.v3; V1 and V2 packages remain supported.

Map each declared profile slot to an existing destination profile. Notification profiles can receive fonts, themes, and footers; document profiles can receive footers. Each differing binding appears separately in the plan. Undeclared bindings remain unchanged. An active profile cannot receive unusable or inactive branding.

Footer templates change only the presentation of an explicitly selected footer definition. Legal, bank, and contact values continue to come from the destination workspace. Templates can arrange fields freely but must retain required content. Invalid templates block import. If a template later fails to produce complete output, rendering uses the complete standard footer and reports the template error. Previously issued documents remain unchanged.

If concurrent changes invalidate a plan, create a new plan in the same dialog. Your target selection is retained and the previous confirmation is discarded.

When installation stores or replaces document templates, branding assets or font files as new Storage objects, it requires a valid default store (storage.default.store_id). Set storage.blob.write_format to stream_v2; the storage backend must support streaming and the Blob-v2 root key must be available. The plan checks these prerequisites and blocks installation if storage is not ready. The package does not change global storage configuration. For guidance on managing the keys, see Blob v2 key inventory.

The plan shows each component and its scope. Document and mail templates apply across the tenant and may affect other shops. Snippets use the destination Site's sales channel. Branding slots require an existing organization, optionally a Commerce profile, and a notification profile when the package declares a mail theme or font binding.

Choose Keep or Replace for every differing component or profile binding. Identical content is reused. Changing targets or decisions invalidates the plan; generate a new plan before applying. Site permissions do not replace the permissions required for the selected resources.

When creating or replacing resources, installation preserves the package's activation state for snippet, document and mail templates, and its status for branding assets, fonts and themes. Inactive templates remain inactive. Keep preserves the state in the destination workspace. Run snippet rebuilds, builds and publication separately. Installation does not publish a Site release; active tenant-wide templates and profile bindings can affect existing document and mail processes.

For V2, pass the same --components-file choices.json to both plan and apply. The JSON object contains targets, keyed by the package's slot names, and decisions, keyed by the plan's component or binding keys. Each decision is keep or replace. Targets contain organizationId and, where required, commerceProfileId and notificationProfileId from the destination workspace.

nucli --tenant <tenant> sites catalog
nucli --tenant <tenant> sites install plan <site-id> \
  --publisher <publisher> --site <site> --version <version>
nucli --tenant <tenant> sites install apply <site-id> \
  --publisher <publisher> --site <site> --version <version> \
  --plan-digest <digest>
nucli --tenant <tenant> sites install status <site-id>

For an authorized commercial purchase, add --purchase-id <purchase-id> --delivery-token-stdin to both plan and apply. The customer account supplies the short-lived token. Do not pass it as a command argument or URL. Plan and apply use the same valid session and package coordinate.

For an external source, use --descriptor-url <https-url> for both plan and apply. The configured source mode must allow the URL. Local ZIP uploads are not supported.

Inspect an interrupted installation

An open installation blocks source access, including the editor, SFTP, preview and builds. Inspect its persisted run in the Sites tab or use:

nucli --tenant <tenant> sites install status <site-id> --run
nucli --tenant <tenant> sites install resume <site-id> <run-id>
nucli --tenant <tenant> sites install abort <site-id> <run-id>

Resume uses the already verified package and the same destination identities. Recovery never starts automatically. A committed installation is not applied again. cleanupPending indicates remaining temporary-file cleanup; manual_review means the recorded evidence cannot safely establish the outcome.

When upgrading the server to this package capability, stop older servers and storage workers before the schema transition. The new baseline prevents the previous server version from starting. Plan the upgrade without running old and new workers together.