Docker-Demo in 10 Minuten

Starten Sie Workspace mit dem veröffentlichten Compose-Bundle. Dafür brauchen Sie keine lokale Repository-Kopie und müssen keinen Root-Key aus einer Terminalausgabe kopieren. Die Demo ist fertig, sobald /health/ready HTTP 200 liefert.

Für produktiven Betrieb nutzen Sie Self-Hosting.

Voraussetzungen

Sie benötigen:

Docker mit docker compose;
Zugriff auf das Workspace-Release und die Container-Registry;
mindestens 4 GB freien Arbeitsspeicher;
ein leeres Arbeitsverzeichnis.

Der erste Image-Download und Schemaaufbau kann deutlich länger als zehn Minuten dauern. Solange /health/live antwortet, ist der Prozess aktiv.

Bundle herunterladen

Öffnen Sie die Release-Übersicht des Workspace-Servers und wählen Sie die gewünschte Version. Laden Sie für diese Anleitung genau dieses Asset herunter:

text

nucleus-server-8.5.0-docker-compose.tar.gz

Die Release-Seite bietet mehrere Dateien an. Für die Docker-Demo benötigen Sie diese Zuordnung:

Release-Datei	Zweck	Erforderlich?
`nucleus-server-8.5.0-docker-compose.tar.gz`	Versionsgleiches Docker-Compose-Bundle mit `compose.yaml`, `README.md` und `start.sh`	Ja
`nucleus-server-8.5.0-linux-amd64.tar.gz`	Standalone-Installation für Linux auf AMD64 ohne Docker Compose	Nein
`README.md`	Installationswege, Verifikation und Betriebshinweise	Nein; Referenz zum Release
`notes.md`	Kurzübersicht der Installationswege und ihrer Artefakte	Nein; Auswahlhilfe
`manifest.txt`	Vollständiges internes Build-Inventar	Nein; Nachweis und Diagnose
`SHA256SUMS`	Prüfsummen für die veröffentlichten Dateien	Ja; zur Downloadprüfung
`release-assets.txt`	Liste der sieben auf der Release-Seite veröffentlichten Dateien	Nein; Übersicht der öffentlichen Assets

Legen Sie SHA256SUMS daneben und prüfen Sie den Download:

bash

sha256sum -c SHA256SUMS --ignore-missing
tar -xzf nucleus-server-8.5.0-docker-compose.tar.gz
cd nucleus-server-docker-compose

Die Prüfsumme muss für das Docker-Archiv OK melden. Brechen Sie ab, wenn die Prüfung fehlschlägt.

Das Compose-Bundle eines Release-Artefakts ist auf genau dessen Image-Tag festgelegt. Prüfen Sie das vor dem Start:

bash

grep 'image:' compose.yaml

Die Ausgabe muss den Release-Tag des Artefakts enthalten, zum Beispiel:

text

git.schukai.me/releases/nucleus:8.5.0

Starten

bash

chmod +x start.sh
./start.sh start --detach
./start.sh status

Das Skript:

erzeugt einmalig .env mit Modus 0600;
legt data/ an;
startet PostgreSQL und nucleus-server onboard;
startet die Container im Hintergrund;
löscht keine Volumes und überschreibt keine vorhandene Konfiguration.

Mit ./start.sh logs verfolgen Sie bei Bedarf die Logausgabe. Durch restart: unless-stopped laufen die Container weiter, wenn Sie die Ansicht mit Ctrl+C beenden.

TLS-Vertrauen einrichten

Beim ersten Start erzeugt Workspace data/nucleus.crt und data/nucleus-tls.key. Das Zertifikat ist der öffentliche Vertrauensanker für die lokale Demo. Der private Schlüssel bleibt beim Server, besitzt Modus 0600 und gehört weder in einen Browser noch in einen CLI- oder MCP-Client.

Prüfen Sie zuerst den serverseitigen Zertifikatsvertrag:

bash

./start.sh doctor

Der Doctor prüft Lesbarkeit, Gültigkeitszeitraum, SANs und das Zertifikat-/Schlüsselpaar. Anschließend ruft er die Health-Endpunkte mit data/nucleus.crt auf. Ein fehlender Browserimport ist ein eigener Client-Trust-Schritt und kein Serverausfall.

Browser und Betriebssystem

Importieren Sie data/nucleus.crt in den Truststore des Browsers oder des Betriebssystems, bevor Sie die Loginseite öffnen. In Chrome öffnen Sie chrome://certificate-manager/localcerts/usercerts, importieren das Zertifikat als lokales Benutzerzertifikat und starten Chrome bei Bedarf neu. Auf verwalteten Geräten kann Ihre Organisation den Truststore zentral pflegen.

Host-CLI und `nucli`

Der Browserimport gilt nicht automatisch für Kommandozeilenprogramme. Nutzen Sie dort den absoluten Pfad zum Zertifikat:

bash

export SSL_CERT_FILE="$(pwd)/data/nucleus.crt"
curl --cacert "$SSL_CERT_FILE" -sS -i https://localhost.alvine.dev:8443/health/ready
nucli --host https://localhost.alvine.dev:8443 discovery
nucli --host https://localhost.alvine.dev:8443 login --email <system-admin-email>

Die Discovery muss die laufende Workspace-Version melden. Erst danach starten Sie den Login.

MCP-Prozess

Ein MCP-Client startet nucli mcp serve als eigenen Prozess. Hinterlegen Sie deshalb auch dort den absoluten Zertifikatspfad:

json

{
  "mcpServers": {
    "nucleus": {
      "command": "nucli",
      "args": ["--tenant", "<mandantenalias>", "mcp", "serve"],
      "env": {
        "SSL_CERT_FILE": "/absoluter/pfad/nucleus-server-docker-compose/data/nucleus.crt"
      }
    }
  }
}

Der Prozess kommuniziert über stdio und öffnet keinen HTTP-Port. Ein manueller Start ohne sichtbare Ausgabe bedeutet, dass er auf MCP-Nachrichten wartet. Die Einrichtung ist abgeschlossen, wenn der MCP-Client die Werkzeugliste abrufen kann.

Fortschritt prüfen

Öffnen Sie ein zweites Terminal:

bash

curl --cacert ./data/nucleus.crt -sS -i https://localhost.alvine.dev:8443/health/live
curl --cacert ./data/nucleus.crt -sS -i https://localhost.alvine.dev:8443/health/ready
curl --cacert ./data/nucleus.crt -sS https://localhost.alvine.dev:8443/health/product-release

Während des Erststarts sind diese Zustände normal:

Antwort	Bedeutung
Verbindung noch nicht möglich	Listener oder TLS wird noch vorbereitet.
`/health/live = 200`, `/health/ready = 503`	Schema oder Produktzustand wird aufgebaut.
`/health/ready = 200`	Workspace ist bereit.

Die Compose-Healthprüfung gewährt dem ersten Schemaaufbau eine Startphase von 15 Minuten. Eine sichtbare Loginseite ersetzt den Readiness-Check nicht.

Anmelden

Öffnen Sie erst nach erfolgreicher Readiness:

text

https://localhost.alvine.dev:8443/login

Beim ersten Start gibt start.sh nur den Pfad data/bootstrap-credentials.json aus. Die Datei hat Modus 0600 und enthält genau die Felder email, password und apiKey. Öffnen Sie die Datei ausschließlich in einer geschützten lokalen Shell und übernehmen Sie die Werte direkt in den freigegebenen Secret-Manager. Kopieren Sie keine Werte in Agentensitzungen, Chats oder Logs.

Prüfen Sie die Anmeldung mit email und password. Entfernen Sie die Datei erst nach einer erfolgreichen neuen Anmeldung. Ein Neustart erzeugt sie nicht erneut. Falls die Datei vor der sicheren Übernahme verloren geht, verwenden Sie ausschließlich den dokumentierten Passwortreset mit dem numin derselben Version. Rekonstruieren Sie die Zugangsdaten weder aus Dateien noch direkt aus der Datenbank. Die Tenant-Erstellung folgt getrennt.

Zeigt Workspace beim ersten Systemzugang die EULA, muss eine vertretungsberechtigte Person sie im Browser prüfen und annehmen. nucli, MCP und andere Headless-Clients können diesen Schritt nicht übernehmen. Die Einordnung erklärt EULA und kommerziellen Hoststatus einordnen.

Port ändern

start.sh leitet die lokale Public URL aus dem Host-Port ab:

bash

NUCLEUS_HTTPS_PORT=9443 ./start.sh

Für eine öffentliche Domain setzen Sie beide Werte:

bash

NUCLEUS_HTTPS_PORT=9443 \
NUCLEUS_PUBLIC_URL=https://workspace.example \
./start.sh

Root-Key sichern

Die Bootstrap-Key-Datei liegt unter data/nucleus-key und besitzt Modus 0600. Sichern Sie sie getrennt von data/nucleus.config.enc.

Für den Wechsel in einen Secret-Manager:

kopieren Sie exakt denselben Key;
mounten Sie ihn als /run/secrets/nucleus-key;
setzen Sie NUCLEUS_KEY_FILE=/run/secrets/nucleus-key;
starten Sie neu und prüfen Sie Fingerprint und /health/ready;
entfernen Sie erst danach die lokale Bootstrap-Datei.

Lokale Storefront-Domain mit DNS-TXT testen

Das Bundle enthält ein optionales CoreDNS-/Caddy-Overlay für shop.localhost.alvine.dev. Der normale ./start.sh aktiviert es nicht. Richten Sie es erst ein, wenn ./start.sh doctor erfolgreich ist.

Der vollständige Ablauf für lokale CA, DNS-TXT-Verifikation, Domainbindung und HTTPS-Prüfung steht unter Lokale Storefront-Domain einrichten. Dort erfahren Sie auch, warum eine Tenant Domain nicht in das Setup-Feld System Domains (CSV) gehört. CSV bedeutet dort kommaseparierte Adminhostnamen, nicht Datei-Upload.

Fehler einordnen

bash

docker compose ps
docker compose logs --tail=200 nucleus
curl --cacert ./data/nucleus.crt -sS https://localhost.alvine.dev:8443/health/product-release

Symptom	Nächster Schritt
PostgreSQL ist nicht healthy	Prüfen Sie `.env`, Volume und freien Speicher.
TLS meldet `bad certificate`	Verwenden Sie `./data/nucleus.crt` als lokalen Vertrauensanker oder installieren Sie Ihre eigene CA.
`./start.sh doctor` meldet einen SAN-Fehler	Verwenden Sie einen Hostnamen aus dem Zertifikat oder ersetzen Sie Zertifikat und Schlüssel als zusammengehöriges Paar.
Browser funktioniert, `nucli` aber nicht	Setzen Sie `SSL_CERT_FILE` für den `nucli`-Prozess auf den absoluten Pfad zu `data/nucleus.crt`.
Product Release bleibt in `retry_wait`	Prüfen Sie die geschützte Statusdiagnose aus der Installationsanleitung.
Product Release ist `failed`	Verwenden Sie die angezeigte Komponente und Aktion; ändern Sie die Datenbank nicht direkt.

Demo stoppen

bash

docker compose down

Dieser Befehl behält Daten und Konfiguration. Löschen Sie Volumes nur, wenn Sie die Demo bewusst vollständig zurücksetzen möchten.

Erfolgskriterien

Die Demo ist erfolgreich, wenn:

beide Container laufen;
/health/ready HTTP 200 liefert;
Sie die System-Admin-Anmeldung öffnen können;
.env und data/nucleus-key Modus 0600 besitzen.

Nächste Schritte

Folgen Sie Von der Docker-Demo zur ersten Live-Site, wenn Sie den vollständigen Weg bis zur ersten veröffentlichten Site durchlaufen möchten.
Legen Sie mit Neuen Mandanten anlegen den ersten Mandanten an.
Richten Sie mit Lokale Storefront-Domain einrichten eine lokale öffentliche Domain ein.
Bauen und veröffentlichen Sie mit CMS-Site prüfen und veröffentlichen die erste Site.
Lesen Sie Serverinstallation für den vollständigen Betriebsvertrag.
Wechseln Sie mit Container und Ingress auf einen festen Hostnamen.
Planen Sie Updates mit Produktupdates ohne manuelle Nacharbeit.