Container und Ingress

Betreiben Sie Workspace als Container hinter einem Reverse Proxy oder Ingress, startet eine neue Installation über nucleus-server onboard. Die Konfiguration bleibt persistent; Business-Traffic wird erst nach erfolgreicher Readiness freigegeben.

Für einen lokalen Test folgen Sie Docker-Demo in 10 Minuten. Für Kubernetes nutzen Sie Kubernetes-Betrieb.

Betriebsmodell

container_ingress browser Browser ingress Reverse Proxy / Ingress browser->ingress HTTPS workspace Workspace :8443 ingress->workspace HTTPS postgres PostgreSQL workspace->postgres volume Persistentes /data workspace->volume key Root-Key-Datei key->workspace

Verwenden Sie für produktive Installationen einen festen Release-Tag:

text
git.schukai.me/releases/nucleus:8.5.0

Ein beweglicher Tag wie latest erschwert Rollback und Support.

Persistente Daten und Secrets

Mounten Sie /data persistent. Dort liegen insbesondere:

  • /data/nucleus.config.enc;
  • /data/storage;
  • beim ersten Onboarding die Bootstrap-Key-Datei.

Übergeben Sie den Root-Key bevorzugt als Datei. Der kanonische externe Mountpunkt lautet /run/secrets/nucleus-key:

text
NUCLEUS_KEY_FILE=/run/secrets/nucleus-key

Die Datei muss für den Prozess lesbar sein und Modus 0600 besitzen. Speichern Sie den Schlüssel nicht im Image, in Git, in Prozessargumenten oder in Logs. Das Onboarding erzeugt bei einer neuen Installation zunächst eine lokale Bootstrap-Datei. Wechseln Sie erst nach erfolgreichem Neustart und Fingerprint-Abgleich auf den externen Mount.

Bestehende Installationen, die NUCLEUS_KEY als Umgebungsvariable verwenden, bleiben ein Migrationsfall. Nutzen Sie für neue Installationen die Datei.

Erster Start

Starten Sie den Server im Vordergrund:

bash
nucleus-server onboard \
  --profile self-hosted \
  --public-url https://workspace.example \
  --listen :8443 \
  --key-file /data/nucleus-key

Das Onboarding:

  1. erzeugt nur fehlende Konfiguration und Schlüsseldateien;
  2. verbindet sich mit PostgreSQL;
  3. baut das Schema und den buildgebundenen Produktzustand auf;
  4. bleibt danach als Serverprozess aktiv.

Ein erneuter Aufruf verwendet die vorhandene Konfiguration. Er überschreibt weder Root-Key noch Konfigurationsdatei.

Healthchecks

Prüfen Sie verschiedene Zustände über getrennte Endpunkte:

EndpunktAussage
/health/liveDer Listener verarbeitet Requests.
/health/readyWorkspace darf Business-Traffic erhalten.
/health/product-releaseDer buildgebundene Produktzustand ist bereit oder noch im Maintenance-Gate.

Der erste Schemaaufbau kann mehrere Minuten dauern. Verwenden Sie eine ausreichende startupProbe oder start_period. Starten Sie den Container nicht neu, solange /health/live antwortet und /health/ready noch 503 liefert.

Beispiel:

bash
curl --fail --silent --show-error \
  https://workspace.example/health/live

curl --fail --silent --show-error \
  https://workspace.example/health/ready

Eine sichtbare Loginseite ist kein Readiness-Nachweis. Erst /health/ready = 200 gibt die Anmeldung und normale APIs frei.

Ingress

Leiten Sie den externen Host konsistent an den internen HTTPS-Port 8443 weiter. Setzen Sie die öffentliche URL auf denselben Browser-Ursprung:

text
NUCLEUS_PUBLIC_URL=https://workspace.example
NUCLEUS_SERVER_LISTEN=:8443

Bewahren Sie Host sowie X-Forwarded-Proto am Proxy. Veröffentlichen Sie nicht PostgreSQL oder interne Diagnoseports.

Wenn der Start nicht fertig wird

Prüfen Sie zuerst:

bash
curl -sS https://workspace.example/health/product-release
docker compose logs --tail=200 nucleus

retry_wait bedeutet, dass Workspace einen buildgebundenen Schritt erneut versucht. Ein terminaler failed-Status benötigt eine Korrektur der angezeigten Komponente oder ein korrigiertes Release. Ändern Sie keine Produktdaten direkt in PostgreSQL.

Für die geschützte Detaildiagnose und den API-Key-Weg folgen Sie Serverinstallation und Produktupdates ohne manuelle Nacharbeit.

Erfolgskriterien

Die Bereitstellung ist abgeschlossen, wenn:

  • /health/live HTTP 200 liefert;
  • /health/ready HTTP 200 liefert;
  • das Container-Image auf einen festen Release-Tag zeigt;
  • /data, PostgreSQL und der Root-Key wiederherstellbar gesichert sind;
  • der Ingress nur die vorgesehenen HTTPS-Routen veröffentlicht.

Nächste Schritte