Server installieren

Installieren Sie mit diesem Ablauf einen selbst betriebenen Workspace-Server. Die Installation ist abgeschlossen, wenn /health/ready mit HTTP 200 antwortet und die System-Admin-Anmeldung verfügbar ist. Tenant-Erstellung und Tenant-Initialisierung folgen als eigene Schritte.

Schnellentscheidung: Loginseite sichtbar, Anmeldung nicht möglich

Laden Sie nicht automatisch eine andere Version. Die Loginseite kann bereits sichtbar sein, während Workspace die Erstinstallation noch fail-closed abschließt. Entscheidend sind die drei getrennten Signale Liveness, Readiness und Product Release:

Ein typischer Wartungszustand sieht gekürzt so aus:

{
  "code": "product_release_not_ready",
  "live": true,
  "ready": false,
  "releaseStatus": "retry_wait",
  "runId": "<run-id>",
  "status": "product_release_maintenance"
}

Lesen Sie live und ready im Betrieb immer zusätzlich von den dedizierten Endpunkten /health/live und /health/ready. Ein Wartungs-JSON aus einer anderen Route ersetzt diese beiden Healthchecks nicht. Die Installation ist erst freigegeben, wenn /health/ready HTTP 200 liefert.

Installationsweg wählen

nucleus-server onboard verbindet Konfiguration, Root-Key-Bootstrap, Serverstart und Product-Release-Fortschritt. Der Befehl bleibt im Vordergrund. Ein erneuter Aufruf prüft die vorhandene Konfiguration und startet den Server, ohne Schlüssel oder Konfiguration zu ersetzen.

Voraussetzungen

Sie benötigen:

• ein freigegebenes Workspace-Image oder nucleus-server-Paket;
• PostgreSQL 18; das Docker-Bundle richtet neue Installationen mit dieser Version ein;
• max_locks_per_transaction muss mindestens 256 betragen; das Docker-Bundle setzt diesen Wert bereits. Starten Sie extern verwaltete PostgreSQL-Instanzen nach einer Änderung der Einstellung neu;
• für native Updates PostgreSQL-Clientwerkzeuge derselben Major-Version wie der Datenbank oder neuer; Rocky 9 benötigt dafür beispielsweise das Paket postgresql18 aus Ihrem freigegebenen PostgreSQL-Repository;
• persistenten Speicher für Konfiguration, Root-Key und Dateien;
• eine öffentliche Administrations-URL für das Profil self-hosted;
• eine Geheimnisverwaltung für Root-Key und Erstzugangsdaten.

Mit Docker in einem Befehl starten

Das Release-Bundle enthält docker/compose.yaml und docker/start.sh. Entpacken Sie das Bundle. Das Release-Bundle enthält bereits den passenden Versionstag. Für einen produktiven Start pinnen Sie das freigegebene Image zusätzlich über seinen unveränderlichen Digest:

cd docker
export NUCLEUS_IMAGE=git.schukai.me/releases/nucleus@sha256:<digest>
./start.sh start --detach
./start.sh status

Das Skript:

• erzeugt einmalig secrets/postgres-password mit Modus 0600;
• speichert in .env nur die lokale Benutzer- und Gruppen-ID;
• legt data/ und backups/ an;
• startet PostgreSQL 18 und den Workspace Server;
• wartet bei --detach auf Readiness;
• löscht keine Volumes;
• überschreibt weder Secret, Root-Key noch Konfiguration.

Öffnen Sie die vom Startskript ausgegebene URL erst nach erfolgreicher Readiness. Das lokale Zertifikat ist selbstsigniert; vertrauen Sie ihm nur in dieser lokalen Testumgebung.

Wenn Readiness nicht erreicht wird, zeigt ./start.sh doctor Containerzustand, Liveness und die relevanten Lifecycle-Meldungen. product_release_maintenance ist dabei kein falsches Passwort: Der Server lebt, hält Login und Business-APIs aber absichtlich geschlossen.

Das Skript wartet standardmäßig bis zu 30 Minuten und meldet alle 30 Sekunden den aktuellen Lifecycle-Fortschritt. Erhöhen Sie auf bewusst langsam provisionierter Hardware bei Bedarf NUCLEUS_STARTUP_TIMEOUT_SECONDS. Terminale Lifecycle-Fehler brechen die Wartezeit weiterhin sofort ab.

Paket oder Binary installieren

Prüfen Sie Paket und Prüfsummen aus demselben Release:

sha256sum -c SHA256SUMS

Installieren Sie danach das passende Artefakt:

# Debian oder Ubuntu
sudo apt install ./nucleus-server_<version>-1_amd64.deb

# RHEL, Fedora oder kompatibel
sudo rpm -Uvh nucleus-server-<version>-1.x86_64.rpm

# Generisches Archiv
tar -xzf nucleus-server-<version>-linux-amd64.tar.gz
cd nucleus-server-<version>-linux-amd64
sudo ./install.sh

Alle drei nativen Wege:

• legt den Systembenutzer nucleus und geschützte Verzeichnisse an;
• staged die neue Version unveränderlich unter /opt/nucleus/releases/<version>;
• installiert die gehärtete systemd-Unit und Diagnosehelfer;
• startet den Dienst nicht;
• migriert bei der Paketinstallation keine bestehende Datenbank.

Prüfen Sie /etc/nucleus/nucleus.env. Passen Sie insbesondere Datenbankhost und öffentliche URL an. Übergeben Sie das Datenbankpasswort danach einmalig über stdin:

read -r -s NUCLEUS_DB_PASSWORD_INPUT
printf '%s\n' "$NUCLEUS_DB_PASSWORD_INPUT" |
  sudo nucleus-server-onboard --db-password-stdin
unset NUCLEUS_DB_PASSWORD_INPUT

Beobachten Sie den Start:

journalctl -u nucleus-server -f
sudo nucleus-server-doctor

nucleus-server-onboard wartet standardmäßig bis zu 30 Minuten auf Readiness und meldet alle 30 Sekunden den Lifecycle-Fortschritt. Ein terminaler Fehler beendet die Wartezeit sofort und ruft die sichere Diagnose auf. Auf bewusst langsam provisionierter Hardware können Sie die Frist mit NUCLEUS_STARTUP_TIMEOUT_SECONDS erhöhen. Übergeben Sie den Wert beim nativen Root-Aufruf explizit, zum Beispiel mit sudo env NUCLEUS_STARTUP_TIMEOUT_SECONDS=3600 nucleus-server-onboard --db-password-stdin.

Onboarding-Profil wählen

Das Archiv verwendet nach install.sh denselben Ablauf wie DEB und RPM. Sie müssen keine eigenen Benutzer, Symlinks oder systemd-Units anlegen. Wählen Sie das Profil und die Verbindungswerte in /etc/nucleus/nucleus.env, lesen Sie das Datenbankpasswort verdeckt ein und geben Sie es einmalig über stdin weiter:

read -r -s NUCLEUS_DB_PASSWORD_INPUT
printf '%s\n' "$NUCLEUS_DB_PASSWORD_INPUT" |
  sudo nucleus-server-onboard --db-password-stdin
unset NUCLEUS_DB_PASSWORD_INPUT

Setzen Sie nicht gleichzeitig NUCLEUS_DB_PASSWORD, NUCLEUS_DB_PASSWORD_FILE und --db-password-stdin. Workspace blockiert widersprüchliche Secret-Quellen.

Das Profil self-hosted akzeptiert generated, existing oder disabled als TLS-Modus. Verwenden Sie disabled nur hinter einer kontrollierten TLS-Terminierung; die öffentliche URL muss dann mit http:// zum internen Listen-Vertrag passen. Weitere Hinweise stehen unter TLS und Reverse Proxy.

Erstzugang sicher übernehmen

Der Server schreibt das einmalig erzeugte Admin-Passwort und den initialen System-API-Key in eine private JSON-Datei mit Modus 0600. Sie enthält genau die Felder email, password und apiKey. Die Runtime-Logs nennen bei erfolgreicher Übergabe nur den Pfad und drucken keine Secret-Werte.

Übernehmen Sie die Datei unmittelbar in Ihre Geheimnisverwaltung. Prüfen Sie danach die System-Admin-Anmeldung und entfernen Sie das Bootstrap-Artefakt am Ursprungsort. Ein Neustart erzeugt es nicht erneut und überschreibt keine vorhandene Datei.

Für Kustomize kopieren Sie die Datei in einer geschützten Admin-Shell, ohne ihren Inhalt in Pod-Logs auszugeben:

umask 077
kubectl -n nucleus exec deployment/nucleus -- \
  cat /data/bootstrap-credentials.json > ./bootstrap-credentials.json
# Nach Übernahme und erfolgreichem Login:
kubectl -n nucleus exec deployment/nucleus -- \
  rm -f /data/bootstrap-credentials.json

Kopieren Sie die Datei nicht in Support-Tickets oder Diagnoseausgaben. Fehlt sie vor dem ersten Login, verwenden Sie den dokumentierten lokalen Admin-Passwortreset mit dem versionsgleichen numin; starten Sie keinen neuen Bootstrap und ändern Sie die Datenbank nicht direkt.

Product-Release-Fortschritt verstehen

Der Server legt vor dem Product-Release-Gate den initialen System-Admin und einen System-API-Key an. Entnehmen Sie den Key ausschließlich der geschützten Credential-Datei. Damit können Sie den Product-Release-Status auch dann prüfen, wenn Readiness noch nicht erreicht ist.

Während des Gates kann die Anmeldeseite bereits sichtbar sein. Eine sichtbare Anmeldeseite bedeutet noch nicht, dass Login oder Business-APIs bereit sind. Verwenden Sie ausschließlich /health/ready als Freigabekriterium.

Prüfen Sie die öffentlichen, begrenzten Zustände:

curl -sk https://127.0.0.1:8443/health/live
curl -sk https://127.0.0.1:8443/health/ready
curl -sk https://127.0.0.1:8443/health/product-release

Falls das Gate wartet oder fehlschlägt, lesen Sie den geschützten Status mit dem initialen System-API-Key. Der Key wird nur über stdin übergeben und nicht in einem nucli-Profil gespeichert:

read -r -s NUCLEUS_BOOTSTRAP_TOKEN
printf '%s\n' "$NUCLEUS_BOOTSTRAP_TOKEN" |
  nucli \
    --host https://workspace.example.com \
    --tenant system \
    system product-release status \
    --watch \
    --token-stdin
unset NUCLEUS_BOOTSTRAP_TOKEN

Bei einem lokalen selbstsignierten Zertifikat vertrauen Sie der ausstellenden CA im Betriebssystem. Beim von Onboarding erzeugten selbstsignierten Zertifikat verwenden Sie nucleus.crt als lokalen Vertrauensanker und setzen bei Bedarf SSL_CERT_FILE auf diese Datei. Verwenden Sie nie den geheimen TLS-Private-Key.

numin product-release status --json bleibt der lokale, read-only Fallback für eine ausdrücklich privilegierte Betriebsumgebung mit Config-, Key- und PostgreSQL-Zugriff. Für einen erreichbaren Server verwenden Sie zuerst nucli.

Wenn Login noch nicht verfügbar ist oder die Zielversion gar nicht bis zum geschützten Status startet, verwenden Sie ausschließlich das numin derselben gestarteten beziehungsweise gestagten Version:

sudo env NUCLEUS_KEY_FILE=/var/lib/nucleus/runtime/nucleus-key \
  /opt/nucleus/releases/<version>/numin \
  --config /var/lib/nucleus/runtime/nucleus.config.enc \
  deployment plan --json
sudo env NUCLEUS_KEY_FILE=/var/lib/nucleus/runtime/nucleus-key \
  /opt/nucleus/releases/<version>/numin \
  --config /var/lib/nucleus/runtime/nucleus.config.enc \
  schema migrations status --json

Diese Diagnose verändert keine Daten. Nutzen Sie kein numin einer älteren Version und führen Sie keine direkten SQL-Reparaturen aus.

Einen Agenten sicher unterstützen lassen

Zeigen Sie einem Agenten zuerst den eingebauten Deployment-Skill:

nucli skills show deployment

Ein MCP-Client kann denselben Vertrag mit nucleus_deployment_skill lesen und anschließend nucleus_deployment_assess aufrufen. Das Assessment arbeitet lokal und read-only. Es benötigt weder Login noch laufende Serververbindung und verändert keine Installation. Übergeben Sie nur normalisierte Beobachtungen wie operation, live, ready, releaseStatus, errorCode, HTTP-Status, TLS-Fehler sowie Transition-Klasse und Point-of-No-Return-Status. Übergeben Sie niemals Passwörter, Tokens, Credential-Dateien, Zertifikat-Keys oder ungefilterte Logs.

Das Assessment liefert eine Klassifikation, versionAction, recoveryMode, konkrete nächste Schritte und Stop-Bedingungen. Die Werte sind eine deterministische Einordnung der übergebenen Beobachtungen. Sie ersetzen weder den Serverstatus noch einen signierten Releasevertrag oder eine Freigabe. Weitere Eingaben und Beispiele finden Sie unter Agenten-Workflows anzeigen.

Fehler einordnen

Laden Sie bei retry_wait oder product_release_maintenance nicht vorsorglich eine andere Version. Diese Zustände bedeuten zunächst, dass die gestartete Version noch arbeitet oder auf eine sichere Wiederholung wartet. Bleiben Sie bei derselben Version und erfassen Sie doctor- und Product-Release-Status. Wechseln Sie nur auf ein vom Anbieter benanntes Forward-Fix. Starten Sie nach einem gemeldeten Point of No Return niemals eine ältere Version.

Die geschützte Diagnose zeigt stabile Fehler-, Begründungs- und Aktionsschlüssel, aber keine internen Fehlerdetails oder Secrets.

Mit Kubernetes installieren

Das Release enthält ein Kustomize-Bundle. Kopieren Sie secret.example.yaml, ersetzen Sie den Platzhalter außerhalb der Versionsverwaltung und passen Sie Datenbankhost sowie öffentliche URL in base/configmap.yaml an. Pinning per Digest ist Pflicht:

cd kustomize/base
kustomize edit set image \
  git.schukai.me/releases/nucleus=git.schukai.me/releases/nucleus@sha256:<digest>
kubectl apply -f ../secret.yaml
kubectl apply -k .
kubectl -n nucleus rollout status deployment/nucleus --timeout=30m

Das PersistentVolume enthält verschlüsselte Konfiguration, Runtime-Key und Storage. Sichern Sie es zusammen mit PostgreSQL. Das Update-Skript führt den Preflight mit numin aus exakt demselben Image-Digest aus.

Root-Key an einen Secret-Manager übergeben

Onboarding erzeugt den Root-Key einmalig mit Modus 0600. Führen Sie die Übergabe in dieser Reihenfolge aus:

1. Kopieren Sie den exakten Bundle-Inhalt in Ihren Secret-Manager.
2. Mounten Sie dieses Secret als /run/secrets/nucleus-key.
3. Setzen Sie NUCLEUS_KEY_FILE=/run/secrets/nucleus-key.
4. Starten Sie den Workspace Server neu und prüfen Sie den gemeldeten Fingerprint sowie /health/ready.
5. Entfernen Sie die lokale Bootstrap-Datei erst nach erfolgreicher Prüfung.

Ein ausdrücklich gewählter, aber fehlender Key-Dateipfad stoppt den Server. Der Workspace Server fällt dann nicht still auf Umgebungsvariable oder lokale Bootstrap-Datei zurück.

Erfolg prüfen

Die Erstinstallation ist abgeschlossen, wenn:

• /health/live HTTP 200 liefert;
• /health/ready HTTP 200 liefert;
• /health/product-release succeeded meldet;
• die System-Admin-Anmeldung funktioniert;
• Root-Key, Erstpasswort und initialer System-API-Key sicher abgelegt sind.

Erstellen und initialisieren Sie erst danach einen Tenant. Der getrennte Tenant-Vertrag ist kein Teil der Server-Erstinstallation.

Nächste Schritte

• Verwalten Sie TLS mit TLS und Reverse Proxy.
• Pflegen Sie öffentliche Hostnamen mit System-Domains verstehen.
• Prüfen Sie Updates mit Produktupdates ohne manuelle Nacharbeit.
• Nutzen Sie Betriebsdiagnose über Diagnose und Readiness.