Self-Hosting

Konfigurationsreferenz

Jede Einstellung von selbst gehostetem Keyright: die vollständige Referenz der Umgebungsvariablen, wie Sie die Secrets erzeugen, Datenbankeinrichtung und Verbindungsstrings, White-Label für Dashboard und Portal sowie die Kubernetes-/Helm-Werte, die Sie tatsächlich setzen werden.

Die vollständige Referenz zur Konfiguration einer selbst gehosteten Instanz. Der Bereitstellungsleitfaden führt Sie der Reihe nach durch das Anwenden dieser Einstellungen; diese Seite ist die, zu der Sie für den exakten Namen und die Bedeutung jeder Einstellung zurückkehren.

Umgebungsvariablen

Setzen Sie diese als Umgebungsvariablen (oder in der Produktion über einen Secrets-Manager).

Variable	Erforderlich	Zweck
`KEYRIGHT_DB`	ja	Npgsql-Verbindungsstring (siehe Datenbank). Compose baut ihn für die mitgelieferte DB aus `POSTGRES_PASSWORD`.
`KEYRIGHT_ADMIN_TOKEN`	ja	Ihr Anbieter-/Admin-Zugangsdatum, das jeden `/admin/`-Aufruf schützt. Der Kunden-Laufzeitpfad (`/v1/`) braucht es nie. Behandeln Sie es wie ein Root-Passwort — ist es nicht gesetzt, antwortet die gesamte Admin-Oberfläche mit 401.
`KEYRIGHT_KEK`	ja	Base64-kodierter 32-Byte-Key-Encryption-Key, der Ihre Signaturschlüssel im Ruhezustand verschlüsselt. Der Service verweigert in Production den Start ohne ihn.
`KEYRIGHT_SELF_LICENSE` / `_FILE`	ja	Ihre Keyright-Lizenz oder Ihr Testschlüssel (Lizenzierung) — inline als JSON oder als Pfad zu einer Datei. Zum Betrieb erforderlich.
`KEYRIGHT_SIGNING_KEY`	empfohlen	Base64-kodierter privater RSA-Schlüssel im PKCS#8-Format, der Offline-Leases und Air-Gapped-Credit-Blöcke signiert. Die Apps Ihrer Kunden betten den passenden öffentlichen Schlüssel ein. Ist er nicht gesetzt, wird in der DB ein Schlüssel pro Mandant erzeugt.
`KEYRIGHT_SELF_LICENSE_GRACE_DAYS`	optional	Schreibgeschütztes Kulanzfenster für bezahlte Lizenzen nach Ablauf (Standard 15).
`KEYRIGHT_LEASE_TTL_DAYS`	optional	Lebensdauer von Online-Leases (Standard 14).
`KEYRIGHT_PUBLIC_URL`	optional	Externer `https://…`-Origin von Dashboard/Portal, damit Links hinter einem Proxy korrekt aufgelöst werden.
`KEYRIGHT_CRON_SECRET`	optional	Schützt die Endpunkte für externe Scheduler (siehe Betrieb → Geplante Jobs).
`KEYRIGHT_BRAND_NAME` / `_COMPANY` / `_LOGO_URL` / `_COLOR` / `_SUPPORT_URL`	optional	White-Label für Dashboard/Portal — eine Enterprise-Funktion (wird nur angewendet, wenn Ihre Lizenz `whitelabel` gewährt; andernfalls die neutrale Keyright-Marke). Siehe White-Label.
`KEYRIGHT_SSO_ISSUER` / `_AUDIENCE` / `_PUBLIC_KEY` / `_AUTHORITY`	optional	Dashboard-SSO (SAML/OIDC) — eine Enterprise-Funktion (nur aktiv, wenn Ihre Lizenz `sso` gewährt).
`KEYRIGHT_GEOIP_URL`	optional	Standortabfrage für Maschinen; für netzwerkisolierte (air-gapped) Läufe leer setzen, um sie zu deaktivieren.
`KEYRIGHT_PORT`	optional	Host-Port für die mitgelieferte Compose-Datei (Standard 8080).
`KEYRIGHT_PLATFORM_TOKEN`	nicht setzen	Der mandantenfähige Modus / Betreibermodus ist eine lizenzierte Funktion nur des verwalteten Service. Dieses Token wird nur beachtet, wenn die Selbstlizenz ein `operator`-Entitlement gewährt — was selbst gehostete Lizenzen nie tun —, sodass es auf einer selbst gehosteten Instanz keine Wirkung hat: Die Instanz ist immer einmandantig und bleibt vollständig lizenzgebunden. Mandantenfähigkeit ist exklusiv dem verwalteten (SaaS-)Service von Keyright vorbehalten.

Secrets erzeugen

openssl rand -hex 24                                                            # KEYRIGHT_ADMIN_TOKEN
openssl rand -base64 32                                                         # KEYRIGHT_KEK (dekodiert zu 32 Bytes)
openssl genrsa 2048 | openssl pkcs8 -topk8 -nocrypt -outform DER | base64 -w0   # KEYRIGHT_SIGNING_KEY

(Unter macOS/BSD hat base64 kein -w0; verwenden Sie ... -outform DER | base64 | tr -d '\n'.) Ihr KEYRIGHT_KEK und Ihr KEYRIGHT_SIGNING_KEY gehören Ihnen — Sie erzeugen sie, wir sehen sie nie. Sichern Sie sie getrennt und sicher: Ohne den KEK können die verschlüsselten Signaturschlüssel in Ihrer Datenbank nicht wiederhergestellt werden.

Datenbank

Sie stellen einen PostgreSQL-Server und eine leere Datenbank bereit; Keyright baut das Schema beim ersten Start selbst auf. Sie importieren nie ein Schema und führen nie SQL von Hand aus — Migrationen sind in das Image kompiliert und laufen automatisch (db.Database.Migrate()), sodass der erste Start und jedes Upgrade ein einziger Schritt sind.

Datenbank und Rolle anlegen

CREATE DATABASE keyright ENCODING 'UTF8' TEMPLATE template0;
CREATE ROLE keyright_app LOGIN PASSWORD 'a-strong-password';
ALTER DATABASE keyright OWNER TO keyright_app;   -- am einfachsten: die App-Rolle besitzt ihre Datenbank

Die App-Rolle muss DDL ausführen können (CREATE/ALTER/DROP), weil Keyright beim Start EF-Core-Migrationen anwendet — der erste Start legt jede Tabelle an und befüllt den Standard-Mandanten; Upgrades wenden nur neue Migrationen an. Die Rolle zum Eigentümer der Datenbank zu machen, ist die einfachste korrekte Einrichtung. 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 Database for PostgreSQL Flexible Server, Cloud SQL) lassen Sie CREATE DATABASE nicht direkt ausführen — legen Sie die leere Datenbank und Rolle stattdessen über deren Konsole/CLI an und vergeben Sie die Rechte dann wie oben. AWS RDS/Aurora, Google Cloud SQL, Azure, Neon, Supabase usw. funktionieren alle.

Verbindungsstring (`KEYRIGHT_DB`)

Npgsql-Format; gegen jedes verwaltete Postgres TLS verlangen:

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

Verwenden Sie Trust Server Certificate=true nur, wenn Sie die Server-CA nicht validieren; bevorzugen Sie in der Produktion SSL Mode=VerifyFull mit einer vertrauenswürdigen CA.

Mitgeliefertes Postgres (nur Evaluierung)

docker compose und das Helm-Chart (postgres.enabled=true) können ein postgres:16 für Sie starten, mit bereits angelegter Datenbank und Rolle sowie einem persistenten Volume. Gut für Evaluierung und kleine Einzelknoten-Installationen; betreiben Sie für die Produktion ein verwaltetes oder hochverfügbares Postgres und richten Sie KEYRIGHT_DB darauf.

White-Label für Dashboard & Portal (Enterprise)

Setzen Sie die Brand-Variablen und starten Sie neu. Sie werden nur angewendet, wenn Ihre Lizenz whitelabel gewährt (Enterprise); bei Standard oder einer abgelaufenen Lizenz wird die neutrale Keyright-Marke verwendet und diese Variablen werden ignoriert. Dafür gibt es beim Self-Hosting keinen „Settings“-Schalter im Dashboard — Branding ist Konfiguration, keine gespeicherte Einstellung.

KEYRIGHT_BRAND_NAME=Acme Licensing                     # ersetzt "Keyright" in Dashboard/Portal + E-Mails
KEYRIGHT_BRAND_COMPANY=Acme GmbH                       # Fußzeile / rechtliche Zeile
KEYRIGHT_BRAND_LOGO_URL=https://cdn.acme.example/logo.svg   # absolute https-URL zu einem Logo (SVG/PNG); weglassen für das Standardzeichen
KEYRIGHT_BRAND_COLOR=#2f63f6                           # Akzentfarbe als Hex #RRGGBB
KEYRIGHT_BRAND_SUPPORT_URL=https://acme.example/support    # Ziel des "Support"-Links

Bestätigen Sie die Anwendung mit GET <base>/branding (liefert Name/Firma/Logo/Farbe live).

Kubernetes-Werte (Helm)

Das Chart in deploy/helm/keyright/ liest diese Werte. Der Bereitstellungsleitfaden enthält die vollständigen helm upgrade --install-Befehle; die Stellschrauben, die Sie am häufigsten setzen werden:

Wert	Zweck
`image.repository` / `image.tag`	Image + Version. Ungesetztes `image.tag` fällt auf die `appVersion` des Charts zurück; pinnen Sie es (z. B. `--set image.tag=2.2.2`) für reproduzierbare Bereitstellungen.
`secrets.adminToken` / `secrets.kek`	Erforderlich — das Chart verweigert das Rendern ohne sie. Mit `--set-string` übergeben.
`secrets.selfLicense`	Ihre Lizenz. Mit `--set-file secrets.selfLicense=license.json` übergeben — nie mit `--set-string` (die Kommas im JSON brechen den Parser).
`postgres.enabled`	`true` (Standard) betreibt ein mitgeliefertes Postgres im Cluster zur Evaluierung; setzen Sie für die Produktion `false` und geben Sie `externalDatabase.connectionString` an.
`postgres.image`	Überschreibt das mitgelieferte DB-Image, z. B. `--set postgres.image=<registry>/postgres:16`, um Docker-Hub-Pull-Limits zu umgehen oder in einem abgeschotteten Cluster.
`externalDatabase.connectionString`	Ihr `KEYRIGHT_DB`, wenn `postgres.enabled=false`. Mit `--set-string` übergeben (enthält Kommas).
`replicaCount`	Anzahl der zustandslosen App-Knoten (2+ für HA — keine Session-Affinität nötig).
`brand.name` / `.company` / `.color` / `.logoUrl` / `.supportUrl`	White-Label (Enterprise). Mit `--set-string` übergeben.
`ingress.`, `resources.`	Ingress-Host/TLS und CPU/Arbeitsspeicher pro Pod. Siehe `values.yaml` für jede Stellschraube.

Die App führt ihre Datenbankmigrationen beim Start aus, daher muss die Datenbank erreichbar sein, wenn der Pod startet — eine nicht erreichbare DB (falscher Host/falsche Zugangsdaten, kein Netzwerkpfad, fehlende Firewall-Regel) versetzt den Pod in CrashLoopBackOff mit einem Npgsql-„connection“-Fehler, nicht in einen Not-Ready-Zustand. Prüfen Sie DNS/Egress zu Ihrer DB, bevor Sie bereitstellen. GET /health ist Liveness; GET /health/ready prüft im laufenden Betrieb zusätzlich die DB-Konnektivität.

Erreichen Sie den Service ohne Ingress per Port-Forward. Der Service heißt <release>-keyright — mit dem Release keyright ergibt das keyright-keyright:

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