Zitadel mit Docker auf einem VPS selbst hosten
Zitadel benötigt etwa 512 MB RAM. Diese Anleitung zeigt PostgreSQL, Masterkey, TLS, SMTP und Backups auf einem VPS sowie die Auswirkungen eines Upgrades.
Was Sie für das Self-Hosting von Zitadel auf einem VPS benötigen
Für das Self-Hosting von Zitadel auf einem VPS benötigen Sie einen Docker-Host, einen öffentlichen DNS-Namen, der auf diesen Host zeigt, PostgreSQL sowie ausreichend CPU und RAM für beide Komponenten. Der Production Guide von Zitadel veranschlagt für die Anwendung selbst etwa 512 MB RAM und weniger als einen CPU-Kern. Der Bedarf der Datenbank und des Passwort-Hashings wächst jedoch. Zitadel ist ein Identity Provider. Über OIDC (OpenID Connect) und SAML (security assertion markup language) stellt es Tokens aus, sodass Ihre anderen Dienste keine eigenen Benutzerlisten mehr verwalten müssen. Die Installation besteht aus einem curl und einem docker compose up. Ob die Installation zuverlässig läuft, hängt vom Masterkey, dem Datenbankbenutzer, SMTP (simple mail transfer protocol), dem Backup und dem ersten Upgrade ab.
Alle folgenden Schritte setzen Ubuntu 24.04, Docker Engine 24 oder neuer mit dem Compose-Plugin in Version 2.24.4 oder neuer sowie einen Namen wie auth.example.com voraus, der bereits auf den Server aufgelöst wird. Die TLS-Overlays verwenden !override. Dafür ist diese Compose-Version erforderlich.
Wie viel VPS-Ressourcen benötigt Zitadel?
Der Compose-Schnellstart in der Zitadel-Dokumentation verlangt 2 GB RAM. Dieser Wert gilt für den Schnellstart. Der Produktionsleitfaden von Zitadel nennt andere Werte.
Die Daten hinter diesem Diagramm
[
{
"config": "Zitadel itself, under 1 core",
"cpu_cores": 0.5,
"ram_gb": 0.5
},
{
"config": "HA node, reduced setup",
"cpu_cores": 4,
"ram_gb": 8
},
{
"config": "HA node, logs and metrics on",
"cpu_cores": 4,
"ram_gb": 16
}
]Das sind veröffentlichte Empfehlungen und keine Messwerte eines laufenden Systems. Betrachten Sie sie als Beschreibung des Ressourcenbedarfs. Der Zitadel-Prozess selbst ist klein: Der Leitfaden veranschlagt dafür etwa 0.5 GB RAM und sagt, dass er mit weniger als einem CPU-Kern laufen kann. Die CPU-Kerne werden für das Hashing von Passwörtern benötigt. Dieses Verfahren ist absichtlich langsam. Dadurch führt eine kurzfristige Anmeldewelle zu einer CPU-Spitze. Der Leitfaden empfiehlt deshalb, dafür 4 CPU-Kerne verfügbar zu halten. PostgreSQL macht den anderen Teil des Ressourcenbedarfs aus: Derselbe Leitfaden veranschlagt etwa einen Kern pro 100 Anfragen pro Sekunde und 4 GB RAM pro Kern.
Die beiden größeren Zeilen enthalten keine Werte für einen einzelnen Server. Für eine minimale hochverfügbare Einrichtung empfiehlt der Leitfaden einen Cluster aus drei Knoten. Jeder Knoten soll 4 Kerne und 16 GB haben. Wenn Sie die Protokollsammlung und die Metriken weglassen, können Sie den Bedarf laut Leitfaden auf etwa 4 Kerne und 8 GB pro Knoten reduzieren. Für einen einzelnen Knoten nennt der Leitfaden keine Dimensionierung.
Ein VPS mit 2 GB startet diesen Stack also. Sobald echter Datenverkehr eintrifft, liegt er deutlich unter dem vom Leitfaden allein für die Datenbank veranschlagten Bedarf. Die Anmeldung ist der Dienst, von dem alle anderen Dienste abhängen. Wenn sie ausfällt, lässt kein Dienst, der ihr vertraut, noch jemanden hinein. Es ist eine vernünftige Entscheidung, den vom Leitfaden veranschlagten Bedarf für Datenbank und Passwort-Hashing als zu hoch für die Authentifizierung einzustufen. Diese Entscheidung ist jetzt deutlich günstiger als nach einer Migration. Der Vergleich von Keycloak, Authentik und Zitadel zeigt, wie viel Arbeitsspeicher und administrativen Aufwand die einzelnen Lösungen benötigen. Ein selbst gehosteter Authentik-Server ist auf einem kleineren System meist die übliche Lösung.
Stack abrufen und eine Version festlegen
mkdir zitadel-compose && cd zitadel-compose
curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/docker-compose.yml
curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/.env.example
cp .env.example .env
chmod 600 .envDiese Datei definiert vier Dienste, die Sie tatsächlich ausführen werden. Traefik ist der Reverse Proxy: Er leitet Anfragen anhand des Pfads weiter und übernimmt mit dem weiter unten beschriebenen Overlay die TLS-Terminierung (transport layer security). zitadel-api ist die Go-Binärdatei auf Port 8080. zitadel-login ist die unter /ui/v2/login bereitgestellte Anmeldeoberfläche. postgres enthält alle Daten. Ein Redis-Cache und ein OpenTelemetry-Collector befinden sich ebenfalls in dieser Datei hinter Compose-Profilen und bleiben deaktiviert, bis Sie sie aktivieren.
Führen Sie docker compose up noch nicht aus. Beim ersten Start wird die Instanz erstellt. Mehrere der folgenden Einstellungen können danach nur mit zusätzlichem Aufwand geändert werden.
Das von Ihnen kopierte .env legt seine eigenen Image-Tags fest:
ZITADEL_VERSION=v4.16.0
TRAEFIK_IMAGE=traefik:v3.7.7
POSTGRES_IMAGE=postgres:17.10-alpineDie aktuelle v4-Version ist v4.20.3 und wurde am 13 November 2026 veröffentlicht. Sie liegt vier Minor-Versionen vor der im ausgelieferten File festgelegten Version. Die Version vor v4.20.0, v4.19.5 vom 15 Oktober 2026, ist die erste Version, die von Zitadel Technical Advisory A-10018 abgedeckt wird: Betroffene Listenendpunkte in den v1- und v2-APIs verwenden nun Standard- und Höchstgrenzen. Ein Client, der ohne Limit listet, erhält daher nicht mehr alle Ergebnisse und muss paginieren. Eine Anfrage, die mehr als das Maximum anfordert, wird abgewiesen. Jede spätere Version, einschließlich v4.20.0, enthält diese Änderung. Setzen Sie ZITADEL_VERSION auf die Version, die Sie ausführen möchten, und bleiben Sie auf der v4-Linie, anstatt immer die neueste Version zu verwenden. Überspringen Sie v4.18.0, wenn Sie eine Version manuell auswählen: In den Release Notes dieser Version steht, dass der Setup-Schritt dort fehlschlägt und stattdessen v4.19.0 verwendet werden soll. Das obige curl ruft docker-compose.yml aus dem main-Branch ab, der auf keinen Commit festgelegt ist. Übertragen Sie daher Ihre Kopie beider Dateien in ein git-Repository. Andernfalls liefert derselbe Befehl auf einem neuen System im nächsten Monat eine andere Datei, und Sie wissen nicht, was sich geändert hat.
Ersetzen Sie LOGIN_SESSION_COOKIE_SECRET in .env durch einen zufälligen Wert, der mit openssl rand -base64 32 erzeugt wurde. Die Login UI verwendet ihn zum Signieren von Sitzungscookies. In den Release Notes von v4.19.5 wird ausdrücklich davor gewarnt, den Beispielwert beizubehalten.
Geben Sie Postgres einen eigenen Benutzer und ein echtes Passwort
Die mitgelieferte .env verbindet Zitadel als Superuser mit PostgreSQL. Das Passwort lautet postgres:
POSTGRES_ADMIN_USER=postgres
POSTGRES_ADMIN_PASSWORD=postgres
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://postgres:postgres@postgres:5432/zitadel?sslmode=disableBei der Härtung gibt es hier eine Falle. Die Zitadel-Dokumentation weist Sie an, POSTGRES_ZITADEL_PASSWORD an .env anzuhängen. Die zugrunde liegende docker-compose.yml liest diese Variable jedoch nie ein. Die Einstellung bewirkt daher nichts. Wenn Sie nur POSTGRES_ADMIN_PASSWORD ändern, schlägt die Verbindung stattdessen fehl, weil das Passwort zusätzlich direkt im DSN-String (Data Source Name) eingetragen ist. Der DSN legt fest, wie Zitadel die Verbindung herstellt.
Die Kommentare in .env.example erklären den Rest eindeutig: Wenn ein DSN konfiguriert ist, verwendet Zitadel diesen Benutzer direkt und erstellt keinen unprivilegierten Benutzer für Sie. Die Rolle muss daher vor dem ersten Start existieren. Erzeugen Sie ein Passwort für die Rolle. Setzen Sie POSTGRES_ADMIN_PASSWORD vor dem Start von Postgres auf ein separates zufälliges Passwort in .env. Starten Sie Postgres anschließend allein und erstellen Sie die Rolle. Das Postgres-Image verwendet dieses Administratorkennwort nur bei der Initialisierung eines leeren Datenverzeichnisses. Wenn Sie .env später ändern, wird das Passwort einer bestehenden Datenbank nicht geändert.
tr -dc A-Za-z0-9 </dev/urandom | head -c 32; echo
docker compose --env-file .env -f docker-compose.yml up -d postgres
docker compose --env-file .env -f docker-compose.yml exec -T postgres \
psql -U postgres -d postgres <<'SQL'
CREATE ROLE zitadel LOGIN PASSWORD 'the-password-you-generated';
ALTER DATABASE zitadel OWNER TO zitadel;
SQLDiese psql-Aufrufe laufen im Container über dessen lokalen Socket. Der offizielle Postgres-Container vertraut diesem Socket, daher wird kein Passwort abgefragt. Entscheidend ist der Besitz der Datenbank. Die Init-Phase von Zitadel erstellt eigene Schemas (eventstore, projections, system) und Tabellen. Der Datenbankbesitz gibt der Rolle das erforderliche CREATE-Recht, um diese Schemas zu initialisieren. Die Änderung der CREATE-Berechtigungen für das public-Schema in PostgreSQL 15 ist davon unabhängig. Sie bedeutet nicht, dass die Schema-Initialisierung von Zitadel fehlschlägt.
Verweisen Sie den DSN nun auf die neue Rolle. Bewahren Sie das Administratorkennwort auf, das Sie vor dem Start von Postgres festgelegt haben:
POSTGRES_ADMIN_PASSWORD=a-32-character-random-string
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://zitadel:the-password-you-generated@postgres:5432/zitadel?sslmode=disablesslmode=disable lässt die Datenbankverbindung im privaten Compose-Netzwerk unverschlüsselt. Der Port wird niemals auf dem Host veröffentlicht. Die Datenbankanleitung von Zitadel empfiehlt TLS für Datenbankverbindungen in Produktionsumgebungen. Prüfen Sie nach dem ersten vollständigen Start, ob die Rolle tatsächlich Besitzer ihrer Daten ist:
docker compose exec -T postgres psql -U zitadel -d zitadel -c '\dn'Dabei sollten ein eventstore-Schema, ein projections-Schema und ein system-Schema aufgelistet werden. Fehlen diese Schemas, ist die Init-Phase nicht bis zu diesem Punkt gekommen. Das Log des API-Containers nennt den Grund.
Der Masterkey und die Folgen seines Verlusts
Zitadel verschlüsselt Secrets, bevor sie gespeichert werden: Zugangsdaten des Identity Providers, das SMTP-Passwort, Seeds für Einmalpasswörter und Maschinenschlüssel. Der Masterkey schließt all diese Daten auf. Er ist genau 32 Bytes lang. Die Dokumentation weist ausdrücklich auf die Folge hin: Er kann nicht geändert werden, ohne den Zugriff auf verschlüsselte Daten zu verlieren.
Generieren Sie einen Masterkey und ersetzen Sie damit die Platzhalterzeile in .env:
tr -dc A-Za-z0-9 </dev/urandom | head -c 32; echoBearbeiten Sie die Zeile ZITADEL_MASTERKEY=MasterkeyNeedsToHave32Characters, statt eine zweite Zeile anzuhängen. Compose verwendet bei einem wiederholten Schlüssel die letzte Definition. Das Anhängen funktioniert daher zwar, aber eine Datei mit zwei Masterkey-Zeilen ist eine Fehlerquelle für die nächste Person, die sie liest.
Prüfen Sie jetzt, wo dieser Schlüssel gespeichert wird. Die Compose-Datei startet den API-Container wie folgt:
command: start-from-init --masterkey "${ZITADEL_MASTERKEY}"Der Masterkey steht damit in der Kommandozeile des Containers. docker inspect zeigt ihn allen Personen, die Zugriff auf den Docker-Socket haben. Auf einem VPS mit nur einer administrierenden Person ist das ein vertretbarer Kompromiss. Die Berechtigungen von .env schützen die Datei auf dem Datenträger. Wenn das nicht akzeptabel ist, mounten Sie den Schlüssel als Datei und verwenden Sie stattdessen --masterkeyFile /run/secrets/zitadel-masterkey. Dadurch bleibt der Wert außerhalb der Prozessargumente.
Kopieren Sie den Masterkey vor dem ersten Start in Ihren Passwortmanager. Er ist nicht in einem Datenbank-Dump enthalten. Wird ein Dump unter einem anderen Masterkey wiederhergestellt, kann die Instanz ihre eigenen Secrets nicht lesen. Bewahren Sie den Masterkey an einem anderen Ort auf als das Archiv mit dem Dump. So enthält ein gestohlenes Backup nicht zugleich die verschlüsselten Daten und den dazugehörigen Schlüssel.
Legen Sie die externe Domain vor dem ersten Start fest
ZITADEL_DOMAIN in .env setzt ZITADEL_EXTERNALDOMAIN im Container. Dabei handelt es sich um den Namen, den Ihre Benutzer eingeben. Zitadel leitet daraus den OIDC-Issuer, die Basis-URI der Anmeldeschnittstelle, die SAML-Endpunkte und den Anmeldenamen des ersten Administrators ab. Der Wert ist daher nicht rein kosmetisch.
ZITADEL_DOMAIN=auth.example.com
ZITADEL_EXTERNALPORT=443
ZITADEL_EXTERNALSECURE=trueZitadel ermittelt anhand des Headers Host, mit welcher Instanz Sie kommunizieren. Wenn dieser Header nicht mit einer bekannten Domain übereinstimmt, antwortet jede Anfrage gleich:
ID=QUERY-1kIjX Message=Instance not foundPrüfen Sie bei diesem Fehler zwei Dinge. Entweder ist ZITADEL_DOMAIN nicht der Name, den Sie im Browser aufrufen, oder ein vorgeschalteter Proxy schreibt Host in die Upstream-Adresse um. Der Fehler tritt ebenfalls auf, wenn Sie statt des Namens die IP-Adresse des Servers aufrufen.
Sie können diese Werte später ändern. Zitadel muss seine Setup-Phase erneut ausführen, damit die Änderung übernommen wird. Jede bereits registrierte Anwendung behält außerdem ihre alten Redirect-URIs. Den endgültigen Namen jetzt festzulegen ist deutlich einfacher, als ihn später zu ändern.
TLS-Terminierung mit dem Let's-Encrypt-Overlay
Für eine öffentliche Domain fügen Sie das Let's-Encrypt-Overlay von Zitadel hinzu. Es stellt Traefik auf die ACME-HTTP-Challenge (Umgebung für die automatische Zertifikatsverwaltung) um und ersetzt die veröffentlichten Ports durch 80 und 443. Daher darf kein anderer Dienst auf dem Server einen dieser beiden Ports belegen.
curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/docker-compose.mode-letsencrypt.yml
echo 'LETSENCRYPT_EMAIL=ops@example.com' >> .envDas Overlay setzt außerdem ZITADEL_EXTERNALPORT: 443 und ZITADEL_EXTERNALSECURE: true am API-Container. Dadurch stimmen die öffentliche URL und die von Zitadel selbst erzeugten URLs überein. Der A-Record muss vor dem Start aufgelöst werden können, weil die HTTP-Challenge andernfalls fehlschlägt.
Wenn Sie TLS bereits mit nginx oder auf einem Load Balancer terminieren, verwenden Sie stattdessen docker-compose.mode-external-tls.yml und setzen TRAEFIK_TRUSTED_IPS auf die Bereiche, aus denen Ihr Proxy Verbindungen sendet. Traefik berücksichtigt X-Forwarded-*-Header nur von Adressen aus dieser Liste. Das Overlay setzt die externe URL und die Login-URLs von Zitadel ausdrücklich auf HTTPS.
Ein vorgeschalteter Proxy muss zwei Anforderungen erfüllen, auf die Zitadel strikt besteht. Er muss HTTP/2 zum Backend verwenden, weil die API gRPC nutzt. Außerdem muss er Host unverändert zusammen mit X-Forwarded-Proto: https weiterleiten. Bei diesem Compose-Stack hat die nginx-Konfiguration folgende Form:
server {
listen 443 ssl;
http2 on;
ssl_certificate /etc/certs/selfsigned.crt;
ssl_certificate_key /etc/certs/selfsigned.key;
location /ui/v2/login {
proxy_pass http://YOUR_LOGIN_UPSTREAM:3000;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto https;
}
location / {
grpc_pass grpc://YOUR_API_UPSTREAM:8080;
grpc_set_header Host $host;
grpc_set_header X-Forwarded-Proto https;
}
}Ersetzen Sie die Platzhalter für das Upstream-Backend durch Adressen, die nginx erreichen kann. Wenn Sie Zitadel auf einem anderen Port als 443 bereitstellen, verwenden Sie grpc_set_header Host $host:$server_port;, damit der Port zusammen mit dem Header übertragen wird. Der Rest ist ein gewöhnlicher Virtual Host. Eine nginx-Reverse-Proxy-Konfiguration Zeile für Zeile lesen behandelt die nicht spezifischen Teile der Zitadel-Konfiguration.
Der erste Administrator und das Erzwingen der Passwortänderung
Beim ersten Start werden eine Instanz, eine Organisation und ein menschlicher Administrator erstellt. Der Anmeldename besteht aus zitadel-admin@, zitadel. und Ihrer externen Domain. Mit ZITADEL_DOMAIN=auth.example.com lautet er:
zitadel-admin@zitadel.auth.example.comDas Passwort lautet Password1!, sofern Sie kein eigenes festlegen. Der Upstream-Standard von Zitadel erzwingt beim ersten Anmelden eine Änderung. Die mitgelieferte Compose-Datei überschreibt diesen Standard:
ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: falseDiese Zeile ist in docker-compose.yml fest codiert und wird nicht aus .env gelesen. Tragen Sie Ihre eigenen Werte daher in einer kleinen eigenen Overlay-Datei ein. Nennen Sie sie docker-compose.local.yml:
services:
zitadel-api:
environment:
ZITADEL_FIRSTINSTANCE_ORG_HUMAN_EMAIL_ADDRESS: you@example.com
ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD: "a-long-temporary-password"
ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: "true"Compose lädt docker-compose.override.yml nur automatisch, wenn Sie es ohne das Flag -f ausführen. Jeder Befehl in der Zitadel-Anleitung übergibt jedoch -f, wodurch dieses Verhalten deaktiviert wird. Statt eine wachsende Liste von Flags zu wiederholen, legen Sie die Dateiliste in .env fest:
COMPOSE_FILE=docker-compose.yml:docker-compose.mode-letsencrypt.yml:docker-compose.local.ymlStarten Sie Zitadel nun:
docker compose pull
docker compose up -d --wait--wait hält den Befehl an, bis die Healthchecks erfolgreich sind. Wenn der API-Container diesen Zustand nie erreicht, bricht Compose mit dependency failed to start: container zitadel-zitadel-api-1 is unhealthy ab. docker compose logs zitadel-api enthält den Grund. Der Container wird nach dem Projekt benannt. Die mitgelieferte Compose-Datei legt diesen Namen selbst mit einem Top-Level-name: zitadel fest, sodass der Verzeichnisname nicht verwendet wird. Beim ersten Start liegt die Ursache meist an der Länge des Masterkeys oder an der Datenbank-DSN.
Melden Sie sich unter https://auth.example.com/ui/console an, ändern Sie das Passwort und aktivieren Sie anschließend einen zweiten Faktor für dieses Konto, bevor Sie weitere Objekte erstellen. Jeder ZITADEL_FIRSTINSTANCE_*-Wert gilt nur während der Erstellung der ersten Instanz. Sobald die Instanz existiert, bewirken Änderungen daran nichts mehr.
Warum die Kennwortzurücksetzung erst funktioniert, wenn SMTP funktioniert
Ein Identity Provider, der keine E-Mails versenden kann, ist auf eine Weise defekt, die wochenlang unbemerkt bleiben kann. Zitadel versendet E-Mails für Benutzereinladungen, die Adressbestätigung, Links zur Kennwortzurücksetzung, Einmalcodes und Hinweise zur Inanspruchnahme von Domains. Wenn kein SMTP-Provider konfiguriert ist, meldet die Console die Aktion trotzdem als abgeschlossen. Die Nachricht wird dann zur Benachrichtigungsverarbeitung übergeben, ohne dass ein Versandziel vorhanden ist. In v4.20.0 verwenden Benachrichtigungen standardmäßig den Legacy-Modus (LegacyEnabled: true). Dieser ignoriert die Einstellungen MaxAttempts: 3 und MaxTtl: 5m des parallelen Workers. Diese Werte beschreiben nicht das standardmäßige Wiederholungsverhalten für Benachrichtigungen. Die Person, die auf den Link wartet, erhält keinen Hinweis.
Konfigurieren Sie den Provider in der Console unter den Instanzeinstellungen bei https://auth.example.com/ui/console/settings. Das SMTP-Provider-Formular fragt nach einer Absender-E-Mail-Adresse, einem Absendernamen, Host und Port, einem Benutzer, einem SMTP-Kennwort und einem TLS-Schalter. Verwenden Sie vor dem Speichern die Testschaltfläche in diesem Formular, da sie eine echte Nachricht versendet: Sie kommt entweder an oder nicht. Aktivieren Sie den Provider, damit Zitadel ihn zum Versand von E-Mails verwendet.
Dafür gibt es passende Umgebungsvariablen: ZITADEL_DEFAULTINSTANCE_SMTPCONFIGURATION_SMTP_HOST und die zugehörigen Variablen. Sie werden angewendet, wenn eine Instanz erstellt wird. Bei einem Stack, der bereits ausgeführt wird, haben sie keine Wirkung. Für eine vorhandene Instanz ist daher die Console der richtige Ort.
Bei der Zustellung von einem VPS sollten Sie zwei Punkte beachten, da der Versand hier häufig fehlschlägt. Prüfen Sie vor der Auswahl eines Relays die Richtlinien Ihres Providers für ausgehendes SMTP: DigitalOcean blockiert auf Droplets standardmäßig die Ports 25, 465 und 587. Port 587 ist daher keine universelle Lösung. Verwenden Sie ein authentifiziertes Relay auf einem Port, den Ihr Provider zulässt. Veröffentlichen Sie außerdem SPF- (sender policy framework) und DKIM- (domainkeys identified mail) Records für die Versanddomain. Andernfalls landet der Link zur Kennwortzurücksetzung im Spam. Für den Benutzer sieht das genauso aus, als wäre die E-Mail nie versendet worden.
In v4.20.0 lehnen ausgehende SMTP-TLS-Verbindungen Zertifikatsketten über die kompromittierten eMudhra-Intermediate-CAs ab. Ein betroffenes Relay benötigt ein Ersatz-Zertifikat.
Prüfen Sie die Funktion, bevor Sie jemanden einladen. Erstellen Sie einen kurzlebigen Benutzer, fordern Sie eine Kennwortzurücksetzung an und beobachten Sie, ob die Nachricht ankommt. Wenn sie nicht ankommt, nennt docker compose logs -f zitadel-api den SMTP-Fehler. Das SMTP-Kennwort wird verschlüsselt in der Datenbank gespeichert. Damit ist es ein weiterer Wert, den der masterkey für Sie schützt.
PostgreSQL und den Masterkey getrennt sichern
Alle Daten, die Zitadel kennt, liegen in PostgreSQL. Der Masterkey entschlüsselt diese Daten. Sichern Sie beides an zwei unterschiedlichen Orten.
Erstellen Sie zuerst den Dump:
sudo install -d -m 700 /srv/zitadel-backups
docker compose exec -T postgres \
pg_dump -U postgres -Fc zitadel > "/srv/zitadel-backups/zitadel-$(date +%F).dump"-Fc ist das benutzerdefinierte Format. Es komprimiert die Daten beim Export, und pg_restore kann daraus gezielt einzelne Inhalte lesen. exec -T deaktiviert das Terminal. Das ist wichtig, weil der Befehl über cron ohne verbundenes Terminal ausgeführt wird.
Übertragen Sie dieses Verzeichnis anschließend mit restic an einen externen Standort. restic verschlüsselt und dedupliziert die Daten:
export RESTIC_REPOSITORY="sftp:backup@backup.example.com:/srv/restic/zitadel"
export RESTIC_PASSWORD_FILE=/root/.restic-password
restic init
restic backup /srv/zitadel-backups
restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prunerestic init wird nur einmal am ersten Tag ausgeführt. Legen Sie den Dump und die beiden letzten Befehle in /usr/local/bin/zitadel-backup.sh ab und führen Sie das Skript jede Nacht aus:
0 3 * * * /usr/local/bin/zitadel-backup.shSichern Sie .env und alle verwendeten Compose-Dateien in git. Der Masterkey ist die einzige Ausnahme. Er gehört in Ihren Passwortmanager und an einen zweiten Speicherort, der nicht dieses restic-Repository ist. Ein Archiv, das Datenbank und Entschlüsselungsschlüssel gemeinsam enthält, ist keine Sicherung eines verschlüsselten Systems mehr.
Ein Backup, das Sie noch nicht wiederhergestellt haben, ist nur eine Vermutung. Stellen Sie es in einer temporären Datenbank auf demselben Server wieder her und prüfen Sie den Inhalt:
docker compose exec -T postgres createdb -U postgres zitadel_restore_test
docker compose exec -T postgres pg_restore -U postgres -d zitadel_restore_test \
< /srv/zitadel-backups/zitadel-2026-08-21.dump
docker compose exec -T postgres psql -U postgres -d zitadel_restore_test -c '\dt eventstore.*'
docker compose exec -T postgres dropdb -U postgres zitadel_restore_testEine Liste von Tabellen im Schema eventstore bedeutet, dass der Dump gültig ist. Meldet der Befehl, dass das Schema nicht existiert, ist der Dump nicht gültig. Sie haben das an einem Tag festgestellt, an dem der Fehler nichts kostet. Das allgemeine Muster zum Sichern und Aktualisieren eines Compose-Stacks gilt hier nahezu unverändert. Den Masterkey aus demselben Archiv herauszuhalten, ist der einzige Zitadel-spezifische Teil.
Upgrade von Zitadel ohne Verlust der Instanz
Ein Upgrade ist eine Versionsanhebung in .env, gefolgt von zwei Befehlen:
docker compose pull
docker compose up -d --waitVerstehen Sie vor der Ausführung, was der zweite Befehl bewirkt, wenn Sie ihn gegen eine Instanz ausführen, an der sich Benutzer anmelden. Der Befehl des Containers lautet start-from-init. Er führt die Phasen init und setup aus, bevor der Container Anfragen verarbeitet. Die setup-Phase enthält die Datenbankmigrationen. Eine Versionsanhebung führt daher beim Start des Containers unbeaufsichtigt Schema-Migrationen gegen Ihre Live-Datenbank aus, während --wait auf einen erfolgreichen Healthcheck wartet. Genau deshalb ist der Wiederherstellungstest oben nicht optional.
Erstellen Sie unmittelbar vor dem Upgrade einen aktuellen Dump. Der Dump von letzter Nacht ist nicht dasselbe.
Bei v4.20.3 müssen laufende Anmeldungen über externe Identity Provider neu gestartet werden. Nicht eingelöste Autorisierungscodes von Login V1 werden einmalig abgelehnt. Benutzerdefinierte Login-UIs benötigen die Berechtigung session.link, um OIDC- oder SAML-Anfragen abzuschließen. Weisen Sie ihrem Servicebenutzer vor dem Upgrade IAM_LOGIN_CLIENT zu. Der mitgelieferte Servicebenutzer von Login V2 hat diese Rolle bereits. Die Kennwortprüfungen der Session API setzen jetzt die Login-Richtlinie der Organisation des Benutzers durch. Organisationen, die die Anmeldung mit Benutzername und Kennwort deaktivieren, müssen Benutzer daher an ihren Identity Provider weiterleiten.
Überspringen Sie keine Hauptversion. Bevor Sie von v3 auf v4 wechseln, aktualisieren Sie zunächst auf v3.4.1 oder höher. v4 macht OIDC-Webschlüssel erforderlich und entfernt den Legacy-Signaturpfad. Wenn Ihre v3-Instanz nie Webschlüssel aktiviert hatte, sind mit den alten Legacy-Schlüsseln signierte Tokens nach dem Upgrade nicht mehr überprüfbar. Zitadel weist in der technischen Empfehlung A-10017 darauf hin, dass vorhandene JWT-Access-Tokens und ID-Tokens sofort ungültig werden können und sich Benutzer möglicherweise erneut anmelden müssen. Die Behebung besteht darin, zunächst über v3.4.1 oder höher zu aktualisieren und ablaufen zu lassen, dass mit Legacy-Schlüsseln signierte Tokens und Sessions ihre Gültigkeit verlieren, bevor Sie das Upgrade durchführen, oder ein geplantes Zeitfenster für erneute Anmeldungen zu akzeptieren. Wenn Sie bereits v3.4.1 oder höher einsetzen und seit der Aktivierung der Webschlüssel gewartet haben, sind laut der Empfehlung keine Maßnahmen erforderlich.
Überwachen Sie die setup-Phase mit docker compose logs -f zitadel-api. Migrationen in einem großen Eventstore dauern mehrere Minuten. Traefik leitet erst dann Anfragen an die API weiter, wenn der Healthcheck erfolgreich ist. Die Website ist während dieses Zeitfensters nicht erreichbar. Planen Sie es ein, statt erst während des Upgrades davon überrascht zu werden.
Ein Rollback besteht nicht einfach darin, wieder den alten Tag zu setzen. Sobald die Migrationen ausgeführt wurden, versteht die ältere Binärdatei das vorgefundene Schema nicht mehr. Ein Rollback bedeutet daher, den Dump wiederherzustellen. Sobald die Instanz echte Benutzer enthält, wechseln Sie zu docker-compose.prodlike.yml. Dieses Overlay führt init und setup als vom Start getrennte Schritte aus. Dadurch lösen Sie eine Migration gezielt aus und überwachen sie, statt sie als Nebenwirkung eines Containerneustarts auszuführen.
Worauf Ihr neuer Identity Provider verweisen muss
Erstellen Sie in der Console ein Projekt und anschließend eine Anwendung darin. Wählen Sie für moderne Anwendungen OIDC. Zitadel stellt Ihnen dann eine Client-ID, ein Client-Secret und ein Discovery-Dokument unter https://auth.example.com/.well-known/openid-configuration bereit. Die meisten selbst gehosteten Anwendungen mit Single-Sign-on-Unterstützung erwarten genau diese Angaben.
Viele Anwendungen unterstützen Single Sign-on nicht oder nur in einem kostenpflichtigen Tarif. Im ersten Fall macht oauth2-proxy vor der Anwendung aus jedem HTTP-Dienst einen Dienst, den Zitadel absichern kann. Im zweiten Fall sollten Sie die SSO-Gebühr bei selbst gehosteten Anwendungen lesen, bevor Sie eine Migration auf Grundlage einer Funktion planen, für die Sie noch nicht bezahlt haben.
FAQ
Wie viel RAM und CPU benötigt ein selbst gehostetes Zitadel?
Laut dem Production Guide von Zitadel benötigt Zitadel selbst etwa 0.5 GB RAM und kann mit weniger als einem CPU-Kern ausgeführt werden. Für das Hashing von Passwörtern werden jedoch 4 Kerne empfohlen. PostgreSQL wird separat dimensioniert: ungefähr ein Kern pro 100 Anfragen pro Sekunde und 4 GB RAM pro Kern. Die größeren Werte im Guide gelten pro Node in einem hochverfügbaren Cluster mit drei Nodes: jeweils 4 Kerne und 16 GB oder etwa 4 Kerne und 8 GB ohne Log-Sammlung und Metriken. Der Compose-Schnellstart verlangt mindestens 2 GB. Das reicht zum Ausprobieren aus, lässt aber wenig Spielraum für die Datenbank, die für weitere Systemdienste benötigt wird.
Was passiert, wenn ich den Zitadel-Masterkey verliere?
Alles, was damit verschlüsselt wurde, bleibt verschlüsselt. Zugangsdaten von Identity Providern, das SMTP-Passwort und Seeds für Einmalpasswörter können nicht entschlüsselt werden. Der Key kann nachträglich nicht geändert werden. Ein Datenbank-Dump allein stellt keine funktionierende Instanz wieder her, weil der Dump Chiffretext, aber keinen Key enthält. Bewahren Sie den Masterkey in einem Passwortmanager und getrennt von dem Backup auf, das den Dump enthält. Wenn beides verloren ist, bleibt nur der vollständige Neuaufbau der Instanz.
Warum kommen E-Mails zum Zurücksetzen von Zitadel-Passwörtern nie an?
Weil kein SMTP-Provider konfiguriert ist oder der konfigurierte Provider die E-Mail nicht zustellen kann. Zitadel v4.20.0 verwendet standardmäßig die Legacy-Benachrichtigungsverarbeitung. Daher werden die Einstellungen des parallelen Workers mit drei Versuchen und fünf Minuten ignoriert. Konfigurieren Sie den SMTP-Provider in den Instance Settings und verwenden Sie die Testschaltfläche in diesem Formular. Dadurch wird eine echte Nachricht gesendet. Aktivieren Sie den Provider, verwenden Sie ein authentifiziertes Relay auf einem Port, den Ihr VPS-Provider zulässt, und veröffentlichen Sie SPF- und DKIM-Einträge für die Absenderdomain. So wird die E-Mail nicht als Spam gefiltert.
Kann ich die externe Domain von Zitadel nach der Installation ändern?
Ja, aber nicht durch eine alleinige Änderung von .env. Ändern Sie ZITADEL_EXTERNALDOMAIN, ZITADEL_EXTERNALPORT und ZITADEL_EXTERNALSECURE. Lassen Sie Zitadel anschließend die Setup-Phase erneut ausführen, damit die Änderung übernommen wird. Bereits registrierte Anwendungen behalten ihre alten Redirect-URIs und müssen manuell aktualisiert werden. Jede Anfrage, deren Host-Header keiner Domain entspricht, die Zitadel kennt, erhält Instance not found zurück. Wenn Sie den endgültigen Namen vor dem ersten Start festlegen, vermeiden Sie diese Probleme.