Bereitstellungsleitfaden (Schritt für Schritt)

Dies ist der lineare Leitfaden nach dem Muster „erst dies, dann das“ zu einer laufenden Instanz. Er setzt voraus, dass Sie die Architekturübersicht überflogen haben. Jede Einstellung, die er berührt, hat eine vollständige Referenz in der Konfiguration; wenn ein Schritt mehr Tiefe braucht, verlinkt er dorthin.

Am Ende haben Sie eine lizenzierte Keyright-Instanz, die auf /health antwortet, ein angemeldetes Dashboard und die exakte Basis-URL, auf die das SDK Ihres Produkts zeigen wird.

Schritt 0 — Voraussetzungen prüfen

• Eine Container-Laufzeitumgebung (empfohlen): Docker 24+ mit Compose v2 oder Kubernetes 1.24+ mit Helm 3. Oder Windows/IIS mit dem .NET 8 Hosting Bundle (Schritt 4C, ohne Container).
• PostgreSQL 14+ (16 empfohlen), UTF-8. Für eine erste Evaluierung können Sie das Bundle eines für Sie starten lassen (Schritt 3); für die Produktion bereiten Sie Ihr eigenes verwaltetes/hochverfügbares Postgres vor.
• Eine Keyright-Lizenz oder ein Testschlüssel von Delta1 — zum Betrieb erforderlich. Kontaktieren Sie den Vertrieb für eine 30-tägige Enterprise-Testversion oder eine bezahlte Standard-/Enterprise-Lizenz. Speichern Sie den erhaltenen Schlüssel als license.json.
• openssl auf der Maschine, von der aus Sie diese Schritte ausführen (zum Erzeugen der Secrets in Schritt 2).

Schritt 1 — Deploy-Kit holen

Das Container-Image ist öffentlich — ziehen Sie es ohne Authentifizierung (pinnen Sie die Version für eine reproduzierbare Installation):

docker pull ghcr.io/delta1-labs/keyright:2.2.2     # oder :latest

Das Deploy-Kit — die Konfigurationsdateien, auf die sich der Rest dieses Leitfadens bezieht — wird Ihnen von Delta1 mit Ihrer Lizenz zugesandt (oder auf Anfrage beim Vertrieb). Es enthält:

• deploy/docker-compose.yml + deploy/.env.example (Docker Compose)
• deploy/helm/keyright/ (Kubernetes / Helm)
• deploy/windows/ (Windows / IIS)

Entpacken Sie es in ein Arbeitsverzeichnis; die folgenden Befehle werden von dort ausgeführt.

Schritt 2 — Secrets erzeugen

Keyright braucht drei Secrets, die Sie erzeugen und aufbewahren. Erzeugen Sie sie jetzt:

openssl rand -hex 24                                                            # KEYRIGHT_ADMIN_TOKEN  (Ihr Root-Admin-Zugangsdatum)
openssl rand -base64 32                                                         # KEYRIGHT_KEK          (verschlüsselt Signaturschlüssel im Ruhezustand — 32 Bytes)
openssl genrsa 2048 | openssl pkcs8 -topk8 -nocrypt -outform DER | base64 -w0   # KEYRIGHT_SIGNING_KEY  (optional; signiert Offline-Leases)

(Unter macOS/BSD hat base64 kein -w0; verwenden Sie ... -outform DER | base64 | tr -d '\n'.)

Sichern Sie den KEK und den Signaturschlüssel getrennt und sicher. Sie gehören Ihnen — wir sehen sie nie — und ohne den KEK können die verschlüsselten Signaturschlüssel in Ihrer Datenbank nicht wiederhergestellt werden. Der Signaturschlüssel ist optional (Keyright erzeugt in der DB einen pro Mandant, wenn Sie ihn weglassen), aber wenn Sie ihn setzen, sichern Sie ihn ebenfalls.

Die vollständige Bedeutung jeder Variable steht in der Konfiguration.

Schritt 3 — Datenbank vorbereiten

Sie stellen einen PostgreSQL-Server und eine leere Datenbank bereit; Keyright baut das Schema beim ersten Start selbst auf — es gibt keine .sql-Datei und kein SQL, das von Hand auszuführen wäre. Migrationen sind in das Image kompiliert und werden bei jedem Start automatisch angewendet (db.Database.Migrate()).

Produktion — Ihr eigenes Postgres. Legen Sie eine leere Datenbank und eine Login-Rolle an und machen Sie die Rolle zum Eigentümer der Datenbank (die einfachste korrekte Einrichtung — die App muss CREATE/ALTER/DROP ausführen können, um Migrationen anzuwenden):

CREATE DATABASE keyright ENCODING 'UTF8' TEMPLATE template0;
CREATE ROLE keyright_app LOGIN PASSWORD 'a-strong-password';
ALTER DATABASE keyright OWNER TO keyright_app;

Wenn die Rolle unter PostgreSQL 15+ nicht der Eigentümer ist, zusätzlich GRANT ALL ON SCHEMA public TO keyright_app;. Manche verwalteten Anbieter (Azure Flexible Server, Cloud SQL) erlauben kein CREATE DATABASE über SQL — legen Sie die leere Datenbank + Rolle über deren Konsole/CLI an und vergeben Sie die Rechte dann wie oben. AWS RDS/Aurora, Cloud SQL, Azure, Neon, Supabase funktionieren alle. Bauen Sie dann Ihren Verbindungsstring (Npgsql-Format, TLS erforderlich):

Host=db.internal.example.com;Port=5432;Database=keyright;Username=keyright_app;Password=...;SSL Mode=Require;Trust Server Certificate=true

Dieser String ist Ihr KEYRIGHT_DB. Siehe Konfiguration → Datenbank für TLS-Optionen und Hinweise zu verwalteten Anbietern.

Evaluierung — diesen Schritt überspringen. Docker Compose und das Helm-Chart können ein postgres:16 für Sie starten, mit bereits angelegter Datenbank und Rolle. Gut für einen ersten Lauf und kleine Einzelknoten-Installationen; wechseln Sie für die Produktion zu Ihrem eigenen verwalteten/hochverfügbaren Postgres.

Schritt 4 — Bereitstellen

Wählen Sie den Pfad, der zu Ihrer Umgebung passt. Alle drei ergeben denselben laufenden Service.

Schritt 4A — Docker Compose (Einzelknoten)

Der schnellste Weg zu einer laufenden Instanz — Postgres + die App auf einem Host:

cp deploy/.env.example deploy/.env        # dann die Secrets aus Schritt 2 eintragen (und KEYRIGHT_DB für die Produktion)
docker compose -f deploy/docker-compose.yml --env-file deploy/.env up -d

Hinterlegen Sie Ihre Lizenz in deploy/.env als KEYRIGHT_SELF_LICENSE (das Lizenz-JSON in einer Zeile) oder mounten Sie eine Datei und setzen Sie KEYRIGHT_SELF_LICENSE_FILE (das Kit enthält ein auskommentiertes volumes:-Beispiel). Pinnen Sie eine Version mit KEYRIGHT_VERSION. Setzen Sie für die Produktion ein echtes KEYRIGHT_DB statt des mitgelieferten Postgres.

Schritt 4B — Kubernetes (Helm)

Speichern Sie Ihre Lizenz in license.json und übergeben Sie sie mit --set-file — verwenden Sie nicht --set/--set-string für die Lizenz oder den DB-String: beide enthalten Kommas/geschweifte Klammern, an denen Helms --set-Parser trennt, was mit key "…" has no value fehlschlägt.

Produktion — Ihr eigenes externes Postgres (empfohlen):

helm upgrade --install keyright deploy/helm/keyright -n keyright --create-namespace \
  --set image.repository=ghcr.io/delta1-labs/keyright \
  --set-string secrets.adminToken="$KEYRIGHT_ADMIN_TOKEN" \
  --set-string secrets.kek="$KEYRIGHT_KEK" \
  --set-file  secrets.selfLicense=license.json \
  --set postgres.enabled=false \
  --set-string externalDatabase.connectionString="Host=db.example.com;Port=5432;Database=keyright;Username=keyright_app;Password=...;SSL Mode=Require;Trust Server Certificate=true" \
  --set replicaCount=2

Evaluierung — mitgeliefertes Postgres im Cluster (die beiden DB-Zeilen oben weglassen und den Standard beibehalten):

helm upgrade --install keyright deploy/helm/keyright -n keyright --create-namespace \
  --set image.repository=ghcr.io/delta1-labs/keyright \
  --set image.tag=2.2.2 \
  --set-string secrets.adminToken="$KEYRIGHT_ADMIN_TOKEN" \
  --set-string secrets.kek="$KEYRIGHT_KEK" \
  --set-file  secrets.selfLicense=license.json

Pinnen Sie die Image-Version. Fügen Sie --set image.tag=<version> hinzu (z. B. --set image.tag=2.2.2) für eine reproduzierbare Bereitstellung. Ungesetzt fällt es auf die appVersion des Charts zurück.

Docker-Hub-Rate-Limits? Das mitgelieferte Postgres zieht postgres:16 von Docker Hub, das anonyme Pulls begrenzt. Wenn der postgres-Pod in ImagePullBackOff hängen bleibt, richten Sie ihn mit --set postgres.image=<registry>/postgres:16 auf Ihre eigene Registry/Ihren eigenen Mirror (siehe Konfiguration → Kubernetes-Werte).

Rechnen Sie beim ersten Start mit mitgeliefertem Postgres mit ein paar Neustarts. Keyright führt seine Migrationen beim Start aus, und das mitgelieferte Postgres braucht einen Moment, bis es Ready ist — bei einer frischen Evaluierungsinstallation kann der App-Pod daher ein paar Mal in CrashLoopBackOff gehen, während er auf die DB wartet. Das ist erwartet, kein Fehler; es löst sich innerhalb von ein bis zwei Minuten, sobald Postgres Ready ist. Mit einem externen Postgres bedeutet eine anhaltende Crash-Schleife dagegen, dass die DB tatsächlich nicht erreichbar ist (siehe Betrieb → Fehlerbehebung).

secrets.adminToken und secrets.kek sind erforderlich — das Chart verweigert das Rendern ohne sie. Siehe Konfiguration → Kubernetes für Ingress, Replikate, Ressourcen, White-Label, das Überschreiben des mitgelieferten Images und das Erreichen des Service per Port-Forward.

Schritt 4C — Windows / IIS

Für Unternehmen, die keine Container betreiben:

pwsh deploy/windows/build-win-bundle.ps1        # -SelfContained ergänzen, wenn auf dem Server kein .NET 8 vorhanden ist

Entpacken Sie .artifacts/keyright-win/keyright-issuing-win-x64.zip in den physischen Pfad einer IIS-Site. Die mitgelieferte web.config verdrahtet das ASP.NET Core Module (in-process). Setzen Sie die KEYRIGHT_*-Werte als Maschinen-Umgebungsvariablen (bevorzugt) oder in web.config, installieren Sie das .NET 8 Hosting Bundle und starten Sie die Site. Richten Sie KEYRIGHT_DB auf Ihr PostgreSQL.

Schritt 5 — Prüfen

curl -fsS http://localhost:8080/health                                        # {"status":"ok","service":"keyright-issuing","version":"2.2.2"}
curl -H "X-Admin-Token: $KEYRIGHT_ADMIN_TOKEN" http://localhost:8080/admin/self-license

/health ist Liveness; /health/ready prüft zusätzlich die Datenbank. /admin/self-license meldet Ihre Edition, phase (active / expiring / grace / gated), verbleibende Tage und ob die Laufzeit blockiert ist — steht dort gated, wurde Ihre Lizenz nicht geladen (siehe Lizenzierung).

Ihre Basis-URL. Bei einem lokalen/Evaluierungslauf ist sie http://localhost:<KEYRIGHT_PORT> (Standard http://localhost:8080); in der Produktion ist sie der Host, den Ihr Load Balancer bedient (z. B. https://licensing.acme.example). Jedes curl und jede SDK-ServiceUrl verwendet ab hier diese Basis.

Unter Kubernetes ohne Ingress erreichen Sie den Service per Port-Forward. Der Service heißt <release>-keyright — für das oben verwendete Release keyright ist das keyright-keyright:

kubectl port-forward -n keyright svc/keyright-keyright 8080:8080

Schritt 6 — Im Dashboard anmelden

Öffnen Sie <base>/dashboard. Auf einer frischen Instanz haben Sie noch keinen Dashboard-Benutzer — melden Sie sich mit Ihrem Admin-Token an: Klappen Sie “Advanced: use an access token” auf, fügen Sie Ihr KEYRIGHT_ADMIN_TOKEN ein und dann View dashboard. (Die Anmeldung mit E-Mail/Passwort braucht einen über POST /admin/team/{id}/set-password bereitgestellten Benutzer; SSO ist die Enterprise-Option KEYRIGHT_SSO_*.) Das Admin-Token ist Ihr Root-Zugangsdatum — behandeln Sie es entsprechend.

Es läuft — wie geht es weiter

• Ihr Produkt an Ihre Instanz anbinden — legen Sie ein Produkt an, erzeugen Sie seinen Signaturschlüssel, richten Sie das SDK Ihrer App auf Ihre Basis-URL und stellen Sie Ihre erste Lizenz aus. Das ist der Schritt, der Self-Hosting real macht.
• Lizenzierung & Editionen — wie Ihr eigener Schlüssel die Instanz freischaltet, die Testversion und Verlängerungen.
• Betrieb & Fehlerbehebung — Skalierung, Backups, Upgrades, Air-Gapped und die Lösung für alles, was oben nicht grün geworden ist.

---

Bei einem Schritt hängen geblieben? Sprechen Sie mit Vertrieb/Support — wir bringen Sie zum Laufen.