Zitadel zelf hosten op een VPS met Docker

Wat u nodig heeft om Zitadel zelf te hosten op een VPS

Om Zitadel zelf te hosten op een VPS heeft u een Docker-host nodig, een publieke DNS-naam die daarnaar verwijst, PostgreSQL en ongeveer 4 CPU-cores met 8 GB RAM. Zitadel is een identity provider. Het geeft tokens uit via OIDC (OpenID Connect) en SAML (Security Assertion Markup Language), zodat uw andere services geen eigen gebruikerslijsten meer hoeven bij te houden. De installatie bestaat uit een curl en een docker compose up. De onderdelen die bepalen of de installatie succesvol blijft, zijn de masterkey, de databasegebruiker, SMTP (Simple Mail Transfer Protocol), de back-up en de eerste upgrade.

Alles hieronder gaat uit van Ubuntu 24.04, Docker Engine 24 of nieuwer met de Compose-plugin, en een naam zoals auth.example.com die al naar de server verwijst.

Hoeveel VPS-capaciteit heeft Zitadel nodig?

De Compose-quickstart in de documentatie van Zitadel vraagt om 2 GB RAM. Dat getal is bedoeld voor een laptop. De productiehandleiding van Zitadel publiceert andere cijfers.

[
  {
    "config": "Process floor, no load",
    "cpu_cores": 0.5,
    "ram_gb": 0.5
  },
  {
    "config": "Single node, reduced setup",
    "cpu_cores": 4,
    "ram_gb": 8
  },
  {
    "config": "HA node, logs and metrics on",
    "cpu_cores": 4,
    "ram_gb": 16
  }
]

Dit zijn gepubliceerde aanbevelingen, geen metingen van een draaiende server. Beschouw ze als een indicatie van de benodigde resources. Het Zitadel-proces zelf is klein, ongeveer 0.5 GB RAM in ruststand. De cores zijn nodig voor het hashen van wachtwoorden; dit proces is bewust traag, waardoor een piek in het aantal aanmeldingen zorgt voor een CPU-piek. PostgreSQL vormt de andere helft van de belasting: dezelfde handleiding rekent met ongeveer één core per 100 verzoeken per seconde en 4 GB RAM per core. Als u deze twee combineert, komt u uit op de 4 cores en 8 GB die de handleiding noemt voor een enkele node, of 16 GB per node zodra logging en metrics zijn ingeschakeld.

Een VPS met 2 GB RAM zal deze stack opstarten, maar dit is minder dan wat het project aanbeveelt voor een serieuze omgeving. De authenticatieservice is de dienst waar alle andere services van afhankelijk zijn. Wanneer deze offline is, krijgt niemand toegang tot systemen die hiervan afhankelijk zijn. Besluiten dat 8 GB meer is dan u wilt uitgeven aan authenticatie is een valide afweging, en het is veel goedkoper om dit nu te beslissen dan na een migratie. De vergelijking tussen Keycloak, Authentik en Zitadel behandelt wat elk pakket kost aan geheugen en operationele inspanning, en een zelfgehoste Authentik-server is doorgaans het antwoord voor een kleinere server.

De stack ophalen en een versie vastzetten

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 .env

Dat bestand definieert vier services die u daadwerkelijk zult draaien. Traefik is de reverse proxy: deze routeert op basis van pad en beëindigt, met de overlay die verderop wordt beschreven, TLS (transport layer security). zitadel-api is het Go-binary op poort 8080. zitadel-login is de login-interface die wordt geserveerd op /ui/v2/login. postgres bevat alles. Een Redis-cache en een OpenTelemetry-collector bevinden zich in hetzelfde bestand achter Compose-profielen en blijven uitgeschakeld totdat u ze opvraagt.

Voer docker compose up nog niet uit. De eerste start creëert de instantie, en diverse instellingen hieronder kunnen daarna niet meer worden gewijzigd zonder extra werk.

De .env die u heeft gekopieerd, zet zijn eigen image-tags vast:

ZITADEL_VERSION=v4.16.0
TRAEFIK_IMAGE=traefik:v3.7.7
POSTGRES_IMAGE=postgres:17.10-alpine

De huidige v4-release is v4.17.1, gepubliceerd op 14 augustus 2026. Stel ZITADEL_VERSION in op de versie die u wilt draaien en blijf op de v4-lijn in plaats van de nieuwste versie te volgen. De curl hierboven haalt docker-compose.yml op uit de main-branch, die aan niets is vastgezet; commit daarom uw kopie van beide bestanden naar een git-repository. Anders geeft hetzelfde commando op een nieuwe machine volgende maand een ander bestand en weet u niet wat er is veranderd.

Geef Postgres een eigen gebruiker en een echt wachtwoord

De meegeleverde .env verbindt Zitadel met PostgreSQL als superuser, met het wachtwoord postgres:

POSTGRES_ADMIN_USER=postgres
POSTGRES_ADMIN_PASSWORD=postgres
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://postgres:postgres@postgres:5432/zitadel?sslmode=disable

Er zit een addertje onder het gras bij de hardening-stap. De documentatie van Zitadel adviseert om POSTGRES_ZITADEL_PASSWORD toe te voegen aan .env, maar de standaard docker-compose.yml leest die variabele nooit uit, waardoor het instellen ervan niets verandert. Het wijzigen van POSTGRES_ADMIN_PASSWORD op zichzelf verbreekt de verbinding, omdat het wachtwoord ook letterlijk in de DSN-string (data source name) staat. De DSN is de regel die bepaalt hoe Zitadel verbinding maakt.

De opmerkingen in .env.example verwoorden het duidelijk: wanneer een DSN is geconfigureerd, gebruikt Zitadel die gebruiker direct en maakt het geen ongeprivilegieerde gebruiker voor u aan. De rol moet dus bestaan vóór de eerste start. Genereer een wachtwoord, start Postgres op zichzelf en maak de rol aan.

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;
SQL

docker compose --env-file .env -f docker-compose.yml exec -T postgres \
  psql -U postgres -d zitadel -c 'ALTER SCHEMA public OWNER TO zitadel;'

Deze psql-aanroepen worden uitgevoerd binnen de container via de lokale socket, die de officiële Postgres-image vertrouwt; daarom wordt er niet om een wachtwoord gevraagd. Eigenaarschap is hierbij cruciaal. Vanaf PostgreSQL 15 en nieuwer staat een standaard GRANT ALL PRIVILEGES ON DATABASE een rol niet langer toe om tabellen aan te maken in het public-schema. Hierdoor faalt de installatiefase van Zitadel met een toegangsrechtenfout tijdens het opbouwen van de schema's. Door de rol eigenaar te maken van de database en het schema, wordt dit voorkomen.

Wijs de DSN nu naar de nieuwe rol en stel een echt beheerderswachtwoord in terwijl u het bestand toch open heeft:

POSTGRES_ADMIN_PASSWORD=a-32-character-random-string
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://zitadel:the-password-you-generated@postgres:5432/zitadel?sslmode=disable

sslmode=disable is hier acceptabel omdat Postgres alleen bereikbaar is via het private Compose-netwerk en de poort nooit wordt gepubliceerd naar de host. Controleer na de eerste volledige start of de rol daadwerkelijk eigenaar is van de data:

docker compose exec -T postgres psql -U zitadel -d zitadel -c '\dn'

Dit zou een eventstore-schema en een projections-schema moeten weergeven. Een lege lijst betekent dat de installatiefase niet zover is gekomen; de logbestanden van de API-container geven aan waarom.

De masterkey en de gevolgen van verlies

Zitadel versleutelt geheimen voordat deze worden opgeslagen: client secrets, inloggegevens van identity providers, het SMTP-wachtwoord, seeds voor eenmalige wachtwoorden en machine keys. De masterkey ontsluit al deze gegevens. Deze is exact 32 tekens lang en de documentatie is helder over de consequenties: de sleutel kan niet worden gewijzigd zonder de toegang tot de versleutelde data te verliezen.

Genereer een sleutel en vervang de placeholder-regel in .env:

tr -dc A-Za-z0-9 </dev/urandom | head -c 32; echo

Bewerk de regel ZITADEL_MASTERKEY=MasterkeyNeedsToHave32Characters in plaats van een tweede regel toe te voegen. Compose gebruikt de laatste definitie van een herhaalde key; toevoegen werkt dus wel, maar een bestand met twee masterkey-regels is verwarrend voor de volgende beheerder.

Denk nu na over de locatie van deze sleutel. Het compose-bestand start de API-container als volgt:

command: start-from-init --masterkey "${ZITADEL_MASTERKEY}"

De masterkey bevindt zich daardoor op de command line van de container, waar docker inspect deze zichtbaar maakt voor iedereen die toegang heeft tot de Docker socket. Op een VPS met één beheerder is dit een acceptabel risico, en de modus op .env beschermt het bestand op schijf. Indien dit niet acceptabel is, mount de sleutel dan als bestand en gebruik in plaats daarvan --masterkeyFile /run/secrets/zitadel-masterkey, waardoor de waarde niet in de procesargumenten verschijnt.

Kopieer de masterkey naar uw wachtwoordbeheerder vóór de eerste start. De sleutel verschijnt niet in een database-dump; een dump die wordt teruggezet onder een andere masterkey resulteert in een instantie die de eigen geheimen niet kan lezen. Bewaar de sleutel op een andere locatie dan het archief waar de dump staat, zodat een gestolen back-up niet zowel de versleutelde data als de bijbehorende sleutel bevat.

Stel het externe domein in vóór de eerste start

ZITADEL_DOMAIN in .env voedt ZITADEL_EXTERNALDOMAIN in de container, en dit is de naam die uw gebruikers intypen. Zitadel leidt hieruit de OIDC-issuer, de basis-URI van de inloginterface, de SAML-endpoints en de inlognaam van de eerste beheerder af; het is dus geen cosmetische instelling.

ZITADEL_DOMAIN=auth.example.com
ZITADEL_EXTERNALPORT=443
ZITADEL_EXTERNALSECURE=true

Zitadel bepaalt met welke instantie u communiceert op basis van de Host-header. Als die header niet overeenkomt met een domein dat bekend is, krijgt elk verzoek hetzelfde antwoord:

ID=QUERY-1kIjX Message=Instance not found

Dit is de meest voorkomende fout bij een zelfgehoste Zitadel-installatie en het betekent bijna altijd een van de twee volgende zaken. Ofwel ZITADEL_DOMAIN is niet de naam die u in uw browser gebruikt, of een proxy aan de voorzijde herschrijft Host naar het upstream-adres. Het browsen naar het IP-adres van de server in plaats van de naam veroorzaakt dit eveneens.

U kunt deze waarden later wijzigen. Zitadel moet echter de setup-fase opnieuw uitvoeren om de wijziging te verwerken, en elke applicatie die u al heeft geregistreerd behoudt zijn oude redirect-URI's. Het kiezen van de definitieve naam op dit moment is aanzienlijk eenvoudiger dan deze later te verplaatsen.

TLS-termination met de Let's Encrypt-overlay

Voeg voor een publiek domein de Let's Encrypt-overlay van Zitadel toe. Deze schakelt Traefik over naar de ACME- (automatic certificate management environment) HTTP-challenge en vervangt de gepubliceerde poorten door 80 en 443. Zorg er daarom voor dat geen enkel ander proces op de server deze poorten bezet.

curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/docker-compose.mode-letsencrypt.yml
echo 'LETSENCRYPT_EMAIL=ops@example.com' >> .env

De overlay stelt ook ZITADEL_EXTERNALPORT: 443 en ZITADEL_EXTERNALSECURE: true in op de API-container. Hierdoor komen de publieke URL en de URL's die Zitadel voor zichzelf genereert overeen. Het A-record moet zijn opgelost voordat u begint, omdat de HTTP-challenge anders faalt.

Als u TLS al beëindigt op nginx of een load balancer, gebruik dan docker-compose.mode-external-tls.yml en stel TRAEFIK_TRUSTED_IPS in op de IP-reeksen waarvandaan uw proxy verkeer verstuurt. Traefik accepteert alleen X-Forwarded-*-headers van adressen uit die lijst. Een onjuiste waarde zorgt ervoor dat het doorgestuurde protocol wordt genegeerd en Zitadel http://-URL's gaat genereren voor een HTTPS-site.

Een upstream-proxy heeft twee taken waar Zitadel strikt op toeziet. De proxy moet HTTP/2 spreken met de backend, omdat de API gRPC gebruikt. Daarnaast moet de proxy Host ongewijzigd doorgeven, samen met X-Forwarded-Proto: https. Het nginx-voorbeeld van Zitadel toont de vereiste configuratie:

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://login-external-tls:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }
    location / {
        grpc_pass grpc://zitadel-external-tls:8080;
        grpc_set_header Host $host;
        grpc_set_header X-Forwarded-Proto https;
    }
}

De upstream-namen in het voorbeeld verwijzen naar de containers in de testopstelling van Zitadel; vervang deze door uw eigen namen. Als u Zitadel op een andere poort dan 443 aanbiedt, gebruik dan grpc_set_header Host $host:$server_port; zodat het poortnummer in de header wordt meegestuurd. De rest is een standaard virtual host-configuratie, en een nginx reverse proxy-configuratie regel voor regel uitgelegd behandelt de onderdelen die niet specifiek voor Zitadel zijn.

De eerste beheerder en het afdwingen van de wachtwoordwijziging

De eerste start creëert één instantie, één organisatie en één menselijke beheerder. De inlognaam is zitadel-admin@ plus zitadel. plus uw externe domein, dus met ZITADEL_DOMAIN=auth.example.com wordt dit:

zitadel-admin@zitadel.auth.example.com

Het wachtwoord is Password1!, tenzij u uw eigen wachtwoord instelt. De standaardinstelling van Zitadel is om een wijziging bij de eerste aanmelding af te dwingen, en het meegeleverde compose-bestand overschrijft die standaardinstelling:

ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: false

Die regel is hardcoded in docker-compose.yml in plaats van dat deze wordt gelezen uit .env, dus plaats uw eigen waarden in een kleine eigen overlay. Noem deze 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 laadt docker-compose.override.yml alleen automatisch wanneer u het uitvoert zonder -f-vlag, en elk commando in de handleiding van Zitadel geeft -f door, wat dit uitschakelt. In plaats van een groeiende lijst met vlaggen te herhalen, zet u de bestandslijst vast in .env:

COMPOSE_FILE=docker-compose.yml:docker-compose.mode-letsencrypt.yml:docker-compose.local.yml

Start het nu:

docker compose pull
docker compose up -d --wait

--wait houdt het commando vast totdat de healthchecks slagen. Wanneer de API-container dit punt nooit bereikt, stopt Compose met dependency failed to start: container zitadel-compose-zitadel-api-1 is unhealthy, en docker compose logs zitadel-api bevat de reden. Bij een eerste start is de reden meestal de lengte van de masterkey of de database DSN.

Log in op https://auth.example.com/ui/console, wijzig het wachtwoord en schakel vervolgens een tweede factor in voor dat account voordat u iets anders aanmaakt. Elke ZITADEL_FIRSTINSTANCE_*-waarde is alleen van toepassing terwijl de eerste instantie wordt aangemaakt. Zodra de instantie bestaat, heeft het bewerken ervan geen enkel effect meer.

Waarom een wachtwoordreset niet werkt totdat SMTP is geconfigureerd

Een identiteitsprovider die geen e-mail kan versturen, is op een manier defect die wekenlang onopgemerkt kan blijven. Zitadel verstuurt e-mail voor gebruikersuitnodigingen, adresverificatie, links voor wachtwoordresets, eenmalige codes en meldingen over domeinclaims. Zonder geconfigureerde SMTP-provider meldt de Console nog steeds dat de actie is voltooid, terwijl het bericht naar een notificatie-worker gaat die het nergens kan afleveren. De standaardinstellingen geven die worker MaxAttempts: 3 en MaxTtl: 5m, waardoor deze het enkele minuten lang een paar keer probeert en daarna stopt. De persoon die op de link wacht, krijgt geen enkele melding.

Configureer dit in de Console, onder de instance-instellingen bij https://auth.example.com/ui/console/settings. Het formulier voor de SMTP-provider vraagt om een afzender-e-mailadres, een afzendernaam, de host en poort, een gebruiker, een SMTP-wachtwoord en een TLS-schakelaar. Gebruik de testknop in dat formulier voordat u opslaat, omdat hiermee een echt bericht wordt verstuurd: het komt aan of het komt niet aan.

Er is een bijbehorende set omgevingsvariabelen, ZITADEL_DEFAULTINSTANCE_SMTPCONFIGURATION_SMTP_HOST en de bijbehorende variabelen. Deze zijn van toepassing wanneer een instance wordt aangemaakt. Op een stack die al draait, hebben ze geen effect; de Console is daarom de juiste plek voor een bestaande instance.

Twee punten over aflevering vanaf een VPS, omdat het daar meestal misgaat. De meeste providers blokkeren uitgaande poort 25 op nieuwe accounts, waardoor een directe verzending naar de mailserver van de ontvanger een time-out geeft zonder bruikbare foutmelding. Gebruik in plaats daarvan een geauthenticeerde relay op poort 587. Publiceer daarnaast SPF (sender policy framework) en DKIM (domainkeys identified mail) records voor het verzendende domein, anders belandt de resetlink in de spam, wat voor de gebruiker precies zo oogt als wanneer de mail nooit is verstuurd.

Test het voordat u iemand uitnodigt. Maak een wegwerpgebruiker aan, vraag een wachtwoordreset aan en controleer of het bericht aankomt. Als dat niet zo is, benoemt docker compose logs -f zitadel-api de SMTP-fout. Het SMTP-wachtwoord wordt versleuteld opgeslagen in de database; dit is nog een item dat de masterkey voor u beheert.

Maak afzonderlijk back-ups van Postgres en de masterkey

Alles wat Zitadel weet, staat in PostgreSQL. De masterkey zorgt voor de ontsleuteling. Sla deze op twee verschillende locaties op.

Eerst de 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 is het aangepaste formaat dat tijdens het exporteren comprimeert en dat pg_restore selectief kan lezen. exec -T negeert de terminal; dit is van belang omdat dit proces via cron draait zonder gekoppelde terminal.

Verplaats die map vervolgens naar een externe locatie met restic, dat versleutelt en ontdubbelt:

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 --prune

restic init draait eenmalig, alleen op de eerste dag. Plaats de dump en de laatste twee commando's in /usr/local/bin/zitadel-backup.sh en voer dit dagelijks uit:

0 3 * * * /usr/local/bin/zitadel-backup.sh

Maak een back-up van .env en elk compose-bestand dat u gebruikt in git. De masterkey vormt hierop de uitzondering. Deze hoort thuis in uw wachtwoordbeheerder en op een tweede locatie die niet deze restic-repository is, omdat een archief dat zowel de database als de bijbehorende ontsleutelingssleutel bevat, geen back-up meer is van een versleuteld systeem.

Een back-up die u niet heeft hersteld, is slechts een aanname. Herstel de data naar een tijdelijke database op dezelfde server en controleer deze:

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_test

Een lijst met tabellen in het eventstore-schema betekent dat de dump valide is. Een foutmelding dat het schema niet bestaat betekent dat dit niet het geval is, en u heeft dit ontdekt op een dag waarop het u niets kost. Het algemene patroon voor het maken van back-ups en het upgraden van een Compose-stack is hier vrijwel ongewijzigd van toepassing, en het gescheiden houden van de masterkey is het enige Zitadel-specifieke onderdeel.

Zitadel upgraden zonder verlies van de instance

Een upgrade is een versie-update in .env gevolgd door twee commando's:

docker compose pull
docker compose up -d --wait

Begrijp wat het tweede commando doet voordat u dit uitvoert op een systeem waar gebruikers op inloggen. Het commando van de container is start-from-init, dat de init- en setup-fasen uitvoert voordat de service start; de setup-fase omvat de database-migraties. Een versie-update voert dus automatisch schema-migraties uit op uw actieve database bij het starten van de container, terwijl --wait wacht op een healthcheck. Dit is de reden waarom de hierboven genoemde restore-test niet optioneel is.

Maak direct voor de upgrade een nieuwe dump. De dump van gisteravond is niet voldoende.

Sla geen major-versie over. Voor de overstap van v3 naar v4 moet u eerst op v3.4.1 of later zitten, omdat v4 de legacy OIDC-ondertekeningssleutels heeft verwijderd. Tokens die met de oude sleutels zijn ondertekend, worden direct ongeldig zodra u overstapt. Het technisch advies A-10017 van Zitadel beschrijft dit; de oplossing is om de nieuwere v3-versie lang genoeg te draaien zodat oude tokens verlopen voordat u upgradet.

Monitor de setup-fase met docker compose logs -f zitadel-api. Migraties op een grote eventstore duren minuten en Traefik routeert pas verkeer naar de API zodra de healthcheck slaagt. De site is gedurende die tijd onbereikbaar. Plan dit in plaats van het te laten overkomen als een verrassing.

Een rollback is niet simpelweg het terugzetten van de oude tag. Zodra de migraties zijn uitgevoerd, begrijpt het oudere binaire bestand het aangetroffen schema niet meer. Een rollback betekent daarom het terugzetten van de dump. Zodra de instance echte gebruikers bevat, stapt u over op docker-compose.prodlike.yml, de overlay die init en setup uitvoert als stappen die losstaan van het starten. Hierdoor is een migratie iets wat u handmatig activeert en monitort, in plaats van een bijwerking van een container-herstart.

Waar u naar moet verwijzen voor uw nieuwe identiteitsprovider

Maak in de Console een project aan en vervolgens een applicatie daarbinnen. Kies OIDC voor moderne toepassingen; Zitadel verstrekt u een client ID, een client secret en een discovery document op https://auth.example.com/.well-known/openid-configuration. De meeste zelfgehoste software die single sign-on ondersteunt, vereist precies deze gegevens.

Veel software ondersteunt dit niet, of alleen in een betaalde versie. Voor het eerste geval verandert oauth2-proxy voor de applicatie elke HTTP-service in iets dat Zitadel kan beveiligen. Voor het tweede geval is het raadzaam om de SSO-belasting in zelfgehoste applicaties te lezen voordat u een migratie plant rondom een functie waarvoor u niet heeft betaald.

FAQ

Hoeveel RAM en CPU heeft een self-hosted Zitadel nodig?

De productiehandleiding van Zitadel adviseert ongeveer 4 CPU-cores en 8 GB RAM voor een enkele node met een beperkte configuratie, en 16 GB per node wanneer logging en metrics zijn ingeschakeld. PostgreSQL wordt apart begroot, op ongeveer één core per 100 verzoeken per seconde en 4 GB RAM per core. De Compose quickstart start binnen 2 GB; dit is voldoende om het te testen, maar minder dan wat het project adviseert voor een systeem waar andere services van afhankelijk zijn.

Wat gebeurt er als ik de Zitadel masterkey verlies?

Alles wat hiermee is versleuteld, blijft versleuteld. Client secrets, inloggegevens van identity providers, het SMTP-wachtwoord en seeds voor eenmalige wachtwoorden kunnen niet worden ontsleuteld, en de sleutel kan achteraf niet worden gewijzigd. Een database-dump op zichzelf herstelt geen werkende instantie, omdat de dump ciphertext bevat en geen sleutel. Sla de masterkey op in een wachtwoordmanager, op een locatie die losstaat van de back-up met de dump. Als beide verloren zijn, is het opnieuw opbouwen van de instantie vanaf nul de enige overgebleven optie.

Waarom komen wachtwoordherstel-e-mails van Zitadel nooit aan?

Omdat er geen SMTP-provider is geconfigureerd, of omdat de geconfigureerde provider niet kan afleveren. Zitadel plaatst elke notificatie standaard in een wachtrij voor een worker met drie pogingen en rapporteert in beide gevallen succes in de Console, waardoor de fout onopgemerkt blijft. Configureer de SMTP-provider onder de instantie-instellingen en gebruik de testknop in dat formulier, die een echt bericht verstuurt. Gebruik vanaf een VPS een geauthenticeerde relay op poort 587, aangezien de meeste providers uitgaand verkeer op poort 25 blokkeren, en publiceer SPF- en DKIM-records voor het verzendende domein zodat de mail niet als spam wordt gefilterd.

Kan ik het externe domein van Zitadel wijzigen na de installatie?

Ja, maar niet door alleen .env te bewerken. Wijzig ZITADEL_EXTERNALDOMAIN, ZITADEL_EXTERNALPORT en ZITADEL_EXTERNALSECURE en laat Zitadel vervolgens de setup-fase opnieuw uitvoeren zodat de wijziging wordt verwerkt. Applicaties die u al heeft geregistreerd behouden hun oude redirect-URI's en moeten handmatig worden bijgewerkt. Elk verzoek waarvan de Host-header niet overeenkomt met een domein dat Zitadel kent, krijgt Instance not found als antwoord. Het kiezen van de definitieve naam vóór de eerste start voorkomt dit alles.