SSD Nodes Learn Hosting plans →
Gidsen Matt ConnorDoor Matt Connor

Zitadel zelf hosten op een VPS met Docker

Leer hoe u Zitadel installeert op een VPS. Wij bespreken de benodigde 512MB RAM, het configureren van PostgreSQL, TLS, SMTP en het veilig uitvoeren van database upgrades.

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 voldoende CPU en RAM voor beide. De productiegids van Zitadel stelt dat de applicatie zelf ongeveer 512 MB RAM en minder dan één CPU-core verbruikt. De database en het hashen van wachtwoorden zijn de onderdelen die groeien. Zitadel is een identity provider. Het geeft tokens uit via OIDC (OpenID Connect) en SAML (security assertion markup language), zodat uw andere services niet langer hun eigen gebruikerslijsten hoeven bij te houden. De installatie bestaat uit een curl en een docker compose up. De onderdelen die bepalen of het systeem blijft werken 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 versie 2.24.4 of nieuwer, en een naam zoals auth.example.com die al naar de server verwijst. De TLS-overlays gebruiken !override, waarvoor die Compose-versie vereist is.

Hoeveel VPS-capaciteit heeft Zitadel nodig?

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

GrafiekZitadel's own published sizing guidance, October 2026
De gegevens achter deze grafiek
[
  {
    "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
  }
]

Dit zijn gepubliceerde aanbevelingen, geen metingen van een actieve server. Beschouw ze als een indicatie van de benodigde resources. Het Zitadel-proces zelf is klein: de handleiding schat het op ongeveer 0.5 GB RAM en stelt dat het op minder dan één CPU-core kan draaien. De cores zijn nodig voor het hashen van wachtwoorden, wat bewust traag is; een piek in het aantal aanmeldingen zorgt dus voor een CPU-piek. De handleiding adviseert om hiervoor 4 CPU-cores beschikbaar te houden. PostgreSQL vormt het andere deel van de belasting: dezelfde handleiding rekent met ongeveer één core per 100 verzoeken per seconde en 4 GB RAM per core.

De twee grotere rijen zijn geen cijfers voor een enkele server. Voor een minimale high-availability opstelling adviseert de handleiding een cluster van drie nodes, elk met 4 cores en 16 GB. U kunt dit terugbrengen naar ongeveer 4 cores en 8 GB per node als u logverzameling en metrics achterwege laat. Er wordt geen dimensionering genoemd voor een enkele node.

Een VPS met 2 GB RAM zal deze stack opstarten, maar dit is ruim onder wat de handleiding voor de database alleen al begroot zodra er daadwerkelijk verkeer binnenkomt. Aanmelding is de service waar alle andere services van afhankelijk zijn. Wanneer deze offline is, krijgt niemand toegang tot de systemen die hiervan afhankelijk zijn. Besluiten dat het budget voor de database en hashing uit de handleiding hoger is dan u wilt uitgeven aan authenticatie is een valide afweging. Het is veel goedkoper om dit nu te beslissen dan na een migratie. De vergelijking tussen Keycloak, Authentik en Zitadel behandelt wat elk systeem 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 verderop, 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.

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

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.20.3, uitgebracht op 13 november 2026, vier minor-versies vooruit op de vastgezette versie in het meegeleverde bestand. De release vóór v4.20.0, v4.19.5 van 15 oktober 2026, is de eerste die wordt gedekt door het technisch advies A-10018 van Zitadel: getroffen lijst-endpoints in de v1- en v2-API's passen nu standaard- en maximumlimieten toe, waardoor een client die een lijst opvraagt zonder limiet niet langer elk resultaat krijgt en moet pagineren, en een verzoek dat om meer dan het maximum vraagt, wordt afgewezen. Elke latere release, inclusief v4.20.0, bevat die wijziging. 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. Sla v4.18.0 over als u handmatig een versie kiest: de release notes vermelden dat de setup-stap in die versie mislukt en adviseren om v4.19.0 te gebruiken. De curl hierboven haalt docker-compose.yml op uit de main-branch, die nergens aan is vastgezet, dus commit uw kopie van beide bestanden naar een git-repository. Anders geeft hetzelfde commando op een nieuwe machine volgende maand u een ander bestand en weet u niet wat er is veranderd.

Vervang LOGIN_SESSION_COOKIE_SECRET in .env door een willekeurige waarde gegenereerd door openssl rand -base64 32. De Login UI gebruikt deze om sessiecookies te ondertekenen, en de release notes van v4.19.5 waarschuwen expliciet tegen het behouden van de voorbeeldwaarde.

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

Hier schuilt een valkuil bij het beveiligen. 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 wijzigen ervan geen effect heeft. Het enkel wijzigen van POSTGRES_ADMIN_PASSWORD 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 verduidelijken dit: 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 voor de rol, stel POSTGRES_ADMIN_PASSWORD in op een apart willekeurig wachtwoord in .env voordat u Postgres start, start vervolgens Postgres zelfstandig en maak de rol aan. De Postgres-image past dat admin-wachtwoord alleen toe bij het initialiseren van een lege datamap; het later wijzigen van .env roteert het wachtwoord van een bestaande database niet.

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

Deze psql-aanroepen worden uitgevoerd binnen de container via de lokale socket, die de officiële Postgres-image vertrouwt, waardoor er niet om een wachtwoord wordt gevraagd. Eigenaarschap is hierbij cruciaal. De init-fase van Zitadel maakt eigen schema's (eventstore, projections, system) en tabellen aan. Database-eigenaarschap geeft de rol het CREATE-privilege dat nodig is om deze schema's te bootstrappen. De wijziging in PostgreSQL 15 met betrekking tot CREATE-rechten op het public-schema staat hier los van en betekent niet dat de schema-bootstrap van Zitadel mislukt.

Wijs de DSN nu naar de nieuwe rol en behoud het admin-wachtwoord dat u instelde voordat u Postgres startte:

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 laat de databaseverbinding ongecodeerd op het private Compose-netwerk; de poort wordt nooit gepubliceerd naar de host. De databasehandleiding van Zitadel adviseert TLS voor databaseverbindingen in productieomgevingen. 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 hoort een eventstore-schema, een projections-schema en een system-schema weer te geven. Als deze schema's ontbreken, is de init-fase niet ver genoeg gekomen en zal het logbestand van de API-container de reden hiervan aangeven.

De masterkey en de kosten van verlies

Zitadel versleutelt geheimen voordat deze worden opgeslagen: inloggegevens van identity providers, het SMTP-wachtwoord, seeds voor eenmalige wachtwoorden en machine keys. De masterkey ontsluit al deze gegevens. Deze is exact 32 bytes groot en de documentatie is helder over de gevolgen: 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 in ZITADEL_MASTERKEY=MasterkeyNeedsToHave32Characters in plaats van een tweede regel toe te voegen. Compose gebruikt de laatste definitie van een herhaalde sleutel; toevoegen werkt dus wel, maar een bestand met twee masterkey-regels is een valstrik 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 daarom 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 de 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 buiten de procesargumenten blijft.

Kopieer de masterkey naar uw wachtwoordmanager 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 met de dump, zodat een gestolen back-up niet zowel de versleutelde data als de bijbehorende sleutel bevat.

Stel het externe domein in voor de eerste start

ZITADEL_DOMAIN in .env voert gegevens in ZITADEL_EXTERNALDOMAIN in de container in, en dit is de naam die uw gebruikers invoeren. 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 bekend domein, krijgt elk verzoek hetzelfde antwoord:

ID=QUERY-1kIjX Message=Instance not found

Controleer twee zaken wanneer u deze foutmelding ziet. Ofwel is ZITADEL_DOMAIN niet de naam die u in uw browser gebruikt, ofwel herschrijft een proxy aan de voorzijde de Host naar het upstream-adres. Navigeren naar het IP-adres van de server in plaats van de domeinnaam veroorzaakt dit eveneens.

U kunt deze waarden later wijzigen. Zitadel moet 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 is daarom efficiënter om nu direct de definitieve naam te kiezen.

TLS-terminatie 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-challenge (automatic certificate management environment) via HTTP 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 mislukt.

Als u TLS al termineert 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 die in deze lijst staan. De overlay stelt de externe URL en de inlog-URL's van Zitadel expliciet in op HTTPS.

Een upstream-proxy heeft twee taken waar Zitadel strikt in is. 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. Bij deze Compose-stack ziet de nginx-configuratie er als volgt uit:

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

Vervang de upstream-placeholders door adressen die nginx kan bereiken. Als u Zitadel op een andere poort dan 443 aanbiedt, gebruik dan grpc_set_header Host $host:$server_port; zodat de poort wordt meegestuurd in de header. De rest is een standaard virtual host, 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 is 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-zitadel-api-1 is unhealthy, en docker compose logs zitadel-api bevat de reden. De container is vernoemd naar het project, en het meegeleverde compose-bestand stelt dit zelf in met een name: zitadel op het hoogste niveau, waardoor de mapnaam niet verschijnt. 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 niets doet totdat SMTP werkt

Een identiteitsprovider die geen e-mail kan versturen, vertoont een gebrek dat 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 de actie als voltooid, waarna het bericht naar de notificatieverwerking gaat zonder bestemming. In v4.20.0 gebruiken notificaties standaard de legacy-modus (LegacyEnabled: true), die de instellingen MaxAttempts: 3 en MaxTtl: 5m van de parallelle worker negeert. Deze waarden beschrijven niet het standaardgedrag voor het opnieuw proberen van notificaties. De gebruiker die op de link wacht, ontvangt 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 e-mailadres van de afzender, een afzendernaam, de host en poort, een gebruiker, een SMTP-wachtwoord en een TLS-schakelaar. Gebruik de testknop in dat formulier voordat u opslaat, aangezien deze een echt bericht verstuurt: het komt aan of niet. Activeer de provider zodat Zitadel deze gebruikt voor het versturen van e-mail.

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, dus de Console is de juiste plek voor een bestaande instance.

Twee zaken over aflevering vanaf een VPS, omdat dit het punt is waar het meestal misgaat. Controleer het uitgaande SMTP-beleid van uw provider voordat u een relay kiest: DigitalOcean blokkeert standaard poort 25, 465 en 587 op Droplets, dus poort 587 is geen universele oplossing. Gebruik een geauthenticeerde relay op een poort die uw provider toestaat. 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 exact hetzelfde lijkt als wanneer de mail nooit is verstuurd.

Op v4.20.0 weigeren uitgaande SMTP TLS-verbindingen certificaatketens die gebruikmaken van de gecompromitteerde eMudhra intermediate CA's. Een getroffen relay heeft een vervangend certificaat nodig.

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

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 de instantie te verliezen

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 het uitvoert op een systeem waar mensen op inloggen. Het commando van de container is start-from-init, dat de init- en setup-fasen uitvoert voordat het begint met serveren, en de setup-fase betreft de database-migraties. Een versie-update voert dus schema-migraties uit op uw live database bij het starten van de container, zonder toezicht, terwijl --wait wacht op een healthcheck. Dat is de reden waarom de bovenstaande restore-test niet optioneel is.

Maak direct vóór de upgrade een verse dump. De dump van gisteravond is iets anders.

Voor v4.20.3 moeten inlogpogingen via externe identity providers die op dat moment bezig zijn, opnieuw worden gestart, en niet-geïnde Login V1-autorisatiecodes worden eenmalig afgewezen. Aangepaste login-UI's hebben session.link-rechten nodig om OIDC- of SAML-verzoeken te voltooien; verleen hun servicegebruiker IAM_LOGIN_CLIENT vóór de upgrade. De meegeleverde Login V2-servicegebruiker heeft die rol al. Wachtwoordcontroles via de Session API dwingen nu het loginbeleid van de organisatie van de gebruiker af, dus organisaties die inloggen met gebruikersnaam/wachtwoord uitschakelen, moeten gebruikers doorsturen naar hun identity provider.

Sla geen major-versie over. Voordat u overstapt van v3 naar v4, moet u eerst naar v3.4.1 of later gaan. v4 maakt OIDC web keys verplicht en verwijdert het legacy signing-pad. Als uw v3-instantie nooit web keys heeft ingeschakeld, zijn tokens die met de oude legacy-keys zijn ondertekend na de upgrade niet langer verifieerbaar. Het technisch advies A-10017 van Zitadel stelt dat bestaande JWT-access tokens en ID-tokens onmiddellijk ongeldig kunnen worden en gebruikers mogelijk opnieuw moeten inloggen. De oplossing is om via v3.4.1 of later te werken en legacy-ondertekende tokens en sessies te laten verlopen voordat u upgradet, of om een gepland venster voor opnieuw inloggen te accepteren. Als u al v3.4.1 of later draait en heeft gewacht sinds web keys werden ingeschakeld, stelt het advies dat er geen actie nodig is.

Monitor de setup-fase met docker compose logs -f zitadel-api. Migraties op een grote eventstore duren minuten, en Traefik zal niet naar de API routeren totdat de healthcheck slaagt, dus de site is gedurende die tijd onbereikbaar. Plan dit in plaats van het te ontdekken.

Een rollback is niet simpelweg het terugplaatsen van de oude tag. Zodra de migraties zijn uitgevoerd, begrijpt de oudere binary het schema dat het aantreft niet, dus een rollback betekent het terugzetten van de dump. Zodra de instantie echte gebruikers bevat, stapt u over naar docker-compose.prodlike.yml, de overlay die init en setup uitvoert als stappen die losstaan van de start, zodat een migratie iets is wat u 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 zelfgehoste Zitadel nodig?

De productiegids van Zitadel stelt dat Zitadel zelf ongeveer 0.5 GB RAM nodig heeft en kan draaien op minder dan één CPU-core; voor wachtwoord-hashing wordt echter aangeraden om 4 cores beschikbaar te houden. PostgreSQL wordt apart begroot, op ongeveer één core per 100 verzoeken per seconde en 4 GB RAM per core. De hogere cijfers in de gids gelden per node in een high-availability cluster van drie nodes: 4 cores en 16 GB per stuk, of ongeveer 4 cores en 8 GB zonder logverzameling en metrics. De Compose quickstart vraagt om minimaal 2 GB; dit is voldoende om het te proberen, maar laat weinig ruimte over voor de database die andere services nodig hebben.

Wat gebeurt er als ik de Zitadel masterkey verlies?

Alles wat hiermee is versleuteld, blijft versleuteld. 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 volledig opnieuw opbouwen van de instantie 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 v4.20.0 gebruikt standaard de verouderde notificatieverwerking, waardoor de instellingen voor drie pogingen en vijf minuten van de parallelle worker worden genegeerd. Configureer de SMTP-provider onder de instantie-instellingen en gebruik de testknop in dat formulier, die een echt bericht verstuurt. Activeer de provider, gebruik een geauthenticeerde relay op een poort die uw VPS-provider toestaat, 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. Door de definitieve naam te kiezen vóór de eerste start, voorkomt u dit volledig.

Was dit artikel nuttig?