Quellen für Workspace Sites steuern

Bei der Installation übernimmt Workspace eine Site als vollständiges, editierbares Sitegenerator-Projekt. Dabei entsteht weder ein Live-Release noch eine Veröffentlichung. Build und Veröffentlichung bleiben eigene, bewusste Schritte.

Quellmodus wählen

Die installationsweite Einstellung cms.site_packages.source_mode kennt drei Modi:

In einer gehosteten Umgebung empfiehlt sich store_only, damit freie Quellen zentral und mandantenübergreifend abgewiesen werden. Bewusst gilt die Richtlinie nicht je Tenant: Einzelne Mandanten können sie nicht lockern.

Die Store-Adresse darf einen festen Dienstpfad enthalten. Für den zentralen schukai-Katalog lautet sie https://www.schukai.com/apps/workspace/sites. Weiterleitungen, Deskriptoren und Archive müssen innerhalb dieses Pfads bleiben. Ein Wechsel auf einen anderen Pfad derselben Domain wird genauso behandelt wie eine externe Quelle.

Unter cms.site_packages.store_trusted_public_keys hinterlegen Sie die vertrauenswürdigen Ed25519-Schlüssel des Katalogs. Vor der Installation prüft Workspace den signierten Release-Deskriptor, den SHA-256-Wert des Archivs und die Hashes aller enthaltenen Dateien. Private Signierschlüssel gehören nicht in die Workspace-Konfiguration. In der gehosteten Lösung bleibt store_only gesperrt; ein Tenant kann dort keine freie Quelle aktivieren.

Eine Site installieren

Im öffentlichen Katalog wählen Sie In Workspace installieren und geben die Basis-URL Ihres Workspace ein. Nach der Anmeldung wählen Sie unter Sites die leere Ziel-Site. Deren Sites-Katalog öffnet sich mit der ausgewählten Vorlage. Die Installation beginnt erst, nachdem Sie den Plan geprüft und bestätigt haben.

Dieser direkte Weg gilt für kostenlose Versionen. Kostenpflichtige Versionen startet der jeweilige Commerce-Store aus dem Kundenkonto; der reine Site-Package-Katalog kennzeichnet sie nur als kostenpflichtigen Kauf.

1. Legen Sie unter CMS > Sites eine leere Site an.
2. Starten Sie eine Development-Session.
3. Öffnen Sie den Tab Sites und wählen Sie eine veröffentlichte Version.
4. Prüfen Sie den Installationsplan. Bestehende Dateien, vorhandene Releases oder fehlende Capabilities blockieren die Installation.
5. Bestätigen Sie die Installation des unveränderten Plans.
6. Bearbeiten und prüfen Sie die übernommenen Quellen im Editor.
7. Bauen und veröffentlichen Sie erst danach einen eigenen Release.

Nach der Installation bleibt die Kopie unabhängig von der Vorlage. Automatische Updates sind in der ersten Version nicht vorgesehen.

Shop-Vorlagen mitinstallieren

Ein Site Package V2 kann zusätzlich Produkt-Snippets, Belegvorlagen, transaktionale Mailvorlagen, Logos, Schriften und Farbgestaltung enthalten. Rechnungen und Lieferscheine verwenden danach weiterhin die vorhandenen Belegprozesse. Der Import erzeugt keine Belege und versendet keine E-Mails.

V3 ergänzt eigenständige ältere Logoressourcen, eigene HTML-Footervorlagen und die Zuordnung mehrerer Benachrichtigungs- und Dokumentprofile. Für diese Pakete muss der Server sitepackage.theme-components.v3 unterstützen. V1- und V2-Pakete bleiben verwendbar.

Wenn die Installation Belegvorlagen, Branding-Assets oder Schriftdateien als neue Storage-Objekte speichert oder ersetzt, benötigt sie einen gültigen Standard-Store (storage.default.store_id). Außerdem muss storage.blob.write_format auf stream_v2 stehen; das Storage-Backend muss Streaming unterstützen und der Blob-v2-Root-Key verfügbar sein. Der Plan prüft diese Voraussetzungen und blockiert bei fehlender Storage-Bereitschaft. Das Paket ändert die globale Storage-Konfiguration nicht. Hinweise zum Umgang mit den Schlüsseln finden Sie unter Blob-v2-Schlüsselinventur.

Der Plan zeigt die enthaltenen Komponenten und ihre Wirkung. Beleg- und Mailvorlagen gelten im gesamten Tenant und können deshalb auch andere Shops betreffen. Snippets werden dem Vertriebskanal der Ziel-Site zugeordnet. Für Branding wählen Sie die vorhandene Organisation und gegebenenfalls das Commerce-Profil; eine deklarierte Mailgestaltung benötigt zusätzlich das passende Benachrichtigungsprofil.

Bei abweichenden Inhalten oder Profilbindungen entscheiden Sie für jeden Konflikt zwischen Beibehalten und Ersetzen. Identische Inhalte werden wiederverwendet. Nach einer Änderung der Ziele oder Entscheidungen erstellen Sie den Plan erneut. Die Installation akzeptiert nur den dazugehörigen aktuellen Plan.

Bei V3 ordnen Sie die deklarierten Profilplätze vorhandenen Profilen im Ziel-Workspace zu. Benachrichtigungsprofile können Schrift, Farbgestaltung und Footer erhalten; Dokumentprofile einen Footer. Jede abweichende Zuordnung erscheint einzeln im Plan. Nicht aufgeführte Zuordnungen bleiben bestehen. Ein aktives Profil darf durch den Import keine unbrauchbare oder inaktive Gestaltung erhalten.

Footervorlagen verändern die Darstellung einer ausdrücklich gewählten Footerdefinition. Rechts-, Bank- und Kontaktdaten kommen weiterhin aus dem Ziel-Workspace. Die Vorlage darf diese Felder frei anordnen, erforderliche Inhalte aber nicht unterdrücken. Ungültige Vorlagen blockieren den Import. Kann eine Vorlage später nicht mehr vollständig ausgegeben werden, verwendet die Ausgabe den vollständigen Standardfooter und meldet den Vorlagenfehler. Bereits ausgestellte Dokumente bleiben unverändert.

Wird der Plan durch eine zwischenzeitliche Änderung ungültig, können Sie ihn im selben Dialog erneut erstellen. Ihre Zielauswahl bleibt erhalten; die alte Bestätigung wird verworfen.

Beim Anlegen oder Ersetzen übernimmt die Installation den Aktivierungszustand der Snippet-, Beleg- und Mailvorlagen sowie den Status der Branding-Assets, Schriften und Themes aus dem Paket. Inaktive Vorlagen bleiben inaktiv. Bei Beibehalten bleibt der Zustand im Ziel-Workspace erhalten. Snippet-Rebuild, Build und Publish führen Sie gesondert aus.

Für diese Schritte benötigen Sie neben den Site-Rechten die Rechte der betroffenen Fachressourcen. Ein Paket enthält Gestaltungsquellen und ausdrücklich gewählte statische Anhänge. Kunden, Bestellungen, Absenderidentitäten, Bankdaten und Zugangsdaten gehören nicht hinein.

Kommerzielle Site Packages installieren

Erst nach bestätigter Zahlungsdeckung erzeugt das Kundenkonto für eine kostenpflichtige Site eine kurze Installationsfreigabe, die der Browser direkt an die ausgewählte Workspace-Site übergibt und die an Kauf, Ziel-Site und Paketversion gebunden bleibt. Sie bleibt flüchtig. URL und Browser-Speicher enthalten sie nicht. Eine spätere Erstattung kann neue Installationen und Downloads sperren; bereits übernommene Quellen und der historische Leistungsnachweis bleiben erhalten.

Mit nucli arbeiten

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>

Für einen berechtigten kommerziellen Kauf ergänzen Plan und Apply jeweils --purchase-id <purchase-id> --delivery-token-stdin. Das Kundenkonto stellt den kurzlebigen Token bereit. Übergeben Sie ihn weder als Argument noch in einer URL. Plan und Apply verwenden dieselbe noch gültige Sitzung und dieselbe Paketkoordinate.

Für eine externe Quelle verwenden Plan und Apply stattdessen --descriptor-url <https-url>. Die URL muss zum konfigurierten Quellmodus passen. Ein lokaler ZIP-Upload gehört nicht zum Vertrag.

Bei V2 übergeben Sie Ziele und Konfliktentscheidungen mit --components-file auswahl.json an Plan und Apply. Beide Aufrufe verwenden dieselbe Datei. Ein Beispiel für die Zuordnung eines deklarierten Slots:

{
  "targets": {
    "shop-branding": {
      "organizationId": "<organization-id>",
      "commerceProfileId": "<commerce-profile-id>",
      "notificationProfileId": "<notification-profile-id>"
    }
  },
  "decisions": {
    "invoice-de": "keep",
    "binding:mail-theme": "replace"
  }
}

Verwenden Sie die Slot- und Komponentenschlüssel aus Ihrem Plan und gültige IDs aus dem Ziel-Workspace. Nicht benötigte optionale Profilzuordnungen lassen Sie weg.

Unterbrochene Installation prüfen

Während einer offenen Installation sind Quellenzugriffe einschließlich Editor, SFTP, Vorschau und Build gesperrt. Nach einem Abbruch prüfen Sie den gespeicherten Lauf im Sites-Tab oder mit:

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>

Eine Wiederaufnahme verwendet das bereits geprüfte Paket und dieselben Zielidentitäten. Der Server startet sie nicht automatisch. Ist die Installation bereits erfolgreich gespeichert, wird sie nicht erneut angewendet. cleanupPending weist auf ausstehende Bereinigung temporärer Dateien hin. Bei manual_review ist der Zustand nicht ausreichend belegt; prüfen Sie den Lauf, bevor Sie weitere Änderungen versuchen.

Beim Serverupgrade auf diese Paketfunktion müssen ältere Server und Storage-Worker vor der Schema-Transition beendet sein. Die neue Baseline erlaubt anschließend keinen Start der vorherigen Serverversion. Planen Sie den Versionswechsel ohne gemischten Betrieb alter und neuer Worker.

Ergebnis prüfen

Abgeschlossen ist die Installation, wenn sites install status die erwartete Koordinate, Version sowie Manifest- und Archiv-Digests ausgibt und die editierbaren Dateien im Development-Projekt vorhanden sind. Die Installation veröffentlicht keinen Site-Release. Aktiv übernommene tenantweite Vorlagen und Profilbindungen können bestehende Beleg- und Mailprozesse beeinflussen.