SSD Nodes Learn Hosting plans →
Guides Matt ConnorPar Matt Connor

Auto-héberger Zitadel sur un VPS avec Docker

Zitadel consomme environ 512 Mo de RAM. Configurez PostgreSQL, la masterkey, TLS, SMTP et les sauvegardes, puis vérifiez l’effet d’une mise à niveau sur la base.

Ce qu’il vous faut pour auto-héberger Zitadel sur un VPS

Pour auto-héberger Zitadel sur un VPS, vous avez besoin d’un hôte Docker, d’un nom DNS public qui pointe vers celui-ci, de PostgreSQL et de suffisamment de CPU et de RAM pour l’ensemble. Le guide de production de Zitadel estime que l’application elle-même utilise environ 512 MB de RAM et moins d’un cœur CPU. Ce sont la base de données et le hachage des mots de passe qui augmentent les besoins. Zitadel est un fournisseur d’identité. Il émet des tokens via OIDC (OpenID Connect) et SAML (security assertion markup language), afin que vos autres services n’aient plus à gérer leurs propres listes d’utilisateurs. L’installation comprend un curl et un docker compose up. Les éléments qui déterminent sa fiabilité sont la masterkey, l’utilisateur de la base de données, SMTP (simple mail transfer protocol), la sauvegarde et la première mise à niveau.

Tout ce qui suit suppose que vous utilisez Ubuntu 24.04, Docker Engine 24 ou une version ultérieure avec le plugin Compose 2.24.4 ou une version ultérieure, ainsi qu’un nom tel que auth.example.com qui résout déjà vers le serveur. Les overlays TLS utilisent !override, qui nécessite cette version de Compose.

De quelles ressources VPS Zitadel a-t-il besoin ?

Le quickstart Compose de la documentation de Zitadel demande 2 GB de RAM. Cette valeur concerne le quickstart. Le guide de mise en production de Zitadel publie des chiffres différents.

GraphiqueZitadel's own published sizing guidance, October 2026
Les données de ce graphique
[
  {
    "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
  }
]

Il s’agit de recommandations publiées, pas de mesures effectuées sur un serveur en fonctionnement. Considérez-les comme une indication de l’ampleur du problème. Le processus Zitadel lui-même est peu gourmand : le guide l’estime à environ 0.5 GB de RAM et indique qu’il peut fonctionner avec moins d’un cœur de CPU. Les cœurs servent au hachage des mots de passe, qui est volontairement lent. Une vague de connexions provoque donc un pic d’utilisation du CPU, et le guide recommande de lui réserver 4 cœurs de CPU. PostgreSQL représente l’autre partie des ressources : le même guide prévoit environ un cœur pour 100 requêtes par seconde et 4 GB de RAM par cœur.

Les deux lignes les plus élevées ne correspondent pas à un serveur unique. Pour une configuration minimale à haute disponibilité, le guide recommande un cluster de trois nœuds, chacun doté de 4 cœurs et de 16 GB de RAM. Il indique que vous pouvez réduire cette configuration à environ 4 cœurs et 8 GB de RAM par nœud si vous désactivez la collecte des logs et les métriques. Il ne fournit aucun dimensionnement pour un nœud unique.

Un VPS de 2 GB démarrera donc cette stack, mais cette capacité est nettement inférieure à ce que le guide prévoit pour la base de données seule lorsque le trafic devient réel. L’authentification est le service dont dépendent tous les autres services. Lorsqu’elle est indisponible, aucun service qui lui fait confiance ne laisse entrer les utilisateurs. Décider que les ressources prévues par le guide pour la base de données et le hachage sont trop élevées pour votre service d’authentification est un choix raisonnable. Il coûte aussi bien moins cher de le faire maintenant qu’après une migration. La comparaison de Keycloak, Authentik et Zitadel explique ce que chacun consomme en mémoire et en travail d’exploitation. Un serveur Authentik auto-hébergé est généralement la solution retenue sur un serveur plus modeste.

Récupérer la stack et figer une version

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

Ce fichier définit quatre services que vous allez réellement exécuter. Traefik est le reverse proxy : il route selon le chemin et, avec l’overlay présenté plus bas, assure la terminaison TLS (transport layer security). zitadel-api est le binaire Go qui écoute sur le port 8080. zitadel-login est l’interface de connexion servie sur /ui/v2/login. postgres contient tous les éléments. Un cache Redis et un collecteur OpenTelemetry se trouvent dans le même fichier derrière des profils Compose et restent désactivés tant que vous ne les activez pas.

N’exécutez pas encore docker compose up. Le premier démarrage crée l’instance, et plusieurs paramètres ci-dessous ne peuvent ensuite plus être modifiés sans opérations supplémentaires.

Le .env que vous avez copié fixe ses propres tags d’image :

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

La version v4 actuelle est v4.20.3, publiée le 13 novembre 2026, soit quatre versions mineures de plus que la version figée dans le fichier fourni. La version précédant v4.20.0, v4.19.5, publiée le 15 octobre 2026, est la première couverte par l’avis technique A-10018 de Zitadel : les endpoints de liste concernés des API v1 et v2 appliquent désormais des limites par défaut et maximales. Un client qui effectue une liste sans limite n’obtient donc plus tous les résultats et doit paginer. Une requête qui demande plus que la limite maximale est rejetée. Toutes les versions ultérieures, y compris v4.20.0, intègrent cette modification. Définissez ZITADEL_VERSION sur la version que vous souhaitez exécuter et restez sur la branche v4 au lieu de suivre la dernière version disponible. Ignorez v4.18.0 si vous choisissez manuellement une version : ses notes de version indiquent que l’étape de configuration échoue dans cette version et recommandent d’utiliser v4.19.0 à la place. Le curl ci-dessus récupère docker-compose.yml depuis la branche main, qui n’est figée sur aucun commit. Enregistrez donc vos copies des deux fichiers dans un dépôt git. Sinon, la même commande exécutée sur un nouveau serveur le mois prochain vous donnera un fichier différent et vous ne saurez pas ce qui a changé.

Remplacez LOGIN_SESSION_COOKIE_SECRET dans .env par une valeur aléatoire générée avec openssl rand -base64 32. La Login UI l’utilise pour signer les cookies de session, et les notes de version de v4.19.5 déconseillent explicitement de conserver la valeur d’exemple.

Attribuer un utilisateur et un mot de passe réel à Postgres

Le .env fourni connecte Zitadel à PostgreSQL avec le compte superuser et le mot de passe postgres :

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

Cette étape de durcissement comporte un piège. La documentation de Zitadel vous demande d’ajouter POSTGRES_ZITADEL_PASSWORD à .env, mais le docker-compose.yml de base ne lit jamais cette variable. La définir ne change donc rien. Modifier uniquement POSTGRES_ADMIN_PASSWORD interrompt au contraire la connexion, car le mot de passe est également écrit en clair dans la chaîne DSN (data source name). La DSN est la ligne qui détermine la manière dont Zitadel se connecte.

Les commentaires de .env.example l’expliquent clairement : lorsqu’une DSN est configurée, Zitadel utilise directement cet utilisateur et ne crée pas lui-même d’utilisateur non privilégié. Le rôle doit donc exister avant le premier démarrage. Générez un mot de passe pour ce rôle, définissez POSTGRES_ADMIN_PASSWORD avec un autre mot de passe aléatoire dans .env avant de démarrer Postgres, puis démarrez Postgres seul et créez le rôle. L’image Postgres n’applique le mot de passe administrateur que lorsqu’elle initialise un répertoire de données vide. Modifier .env par la suite ne change pas le mot de passe d’une base de données existante.

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

Ces appels psql s’exécutent à l’intérieur du conteneur via son socket local, que l’image Postgres officielle autorise sans authentification par mot de passe. C’est la propriété qui compte. La phase d’initialisation de Zitadel crée ses propres schémas (eventstore, projections, system) et tables. La propriété de la base de données donne au rôle le privilège CREATE nécessaire pour initialiser ces schémas. La modification de PostgreSQL 15 concernant les permissions CREATE sur le schéma public est indépendante et n’implique pas que l’initialisation des schémas de Zitadel échoue.

Pointez maintenant la DSN vers le nouveau rôle et conservez le mot de passe administrateur défini avant le démarrage de Postgres :

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 laisse la connexion à la base de données non chiffrée sur le réseau Compose privé ; son port n’est jamais publié sur l’hôte. Le guide de Zitadel consacré aux bases de données recommande TLS pour les connexions aux bases de données en production. Après le premier démarrage complet, vérifiez que le rôle possède bien ses données :

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

La commande doit afficher un schéma eventstore, un schéma projections et un schéma system. Si ces schémas sont absents, la phase d’initialisation ne les a jamais créés. Le journal du conteneur API indiquera pourquoi.

La masterkey, et le coût de sa perte

Zitadel chiffre les secrets avant de les stocker : identifiants du fournisseur d’identité, mot de passe SMTP, seeds des mots de passe à usage unique et clés machine. La masterkey permet de déchiffrer toutes ces données. Elle fait exactement 32 octets. La documentation est claire sur la conséquence : il est impossible de la modifier sans perdre l’accès aux données chiffrées.

Générez-en une, puis remplacez la ligne placeholder dans .env :

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

Modifiez la ligne ZITADEL_MASTERKEY=MasterkeyNeedsToHave32Characters au lieu d’en ajouter une seconde. Compose utilise la dernière définition d’une clé répétée. L’ajout fonctionne donc, mais un fichier contenant deux lignes masterkey risque d’induire en erreur la prochaine personne qui le consultera.

Réfléchissez maintenant à l’endroit où cette clé est stockée. Le fichier Compose démarre le conteneur API comme ceci :

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

La masterkey se trouve donc dans la ligne de commande du conteneur. docker inspect l’affiche à toute personne pouvant accéder au socket Docker. Sur un VPS administré par une seule personne, ce compromis est acceptable. Les permissions de .env protègent la clé sur le disque. Si ce compromis ne vous convient pas, montez la clé en tant que fichier et utilisez plutôt --masterkeyFile /run/secrets/zitadel-masterkey. Sa valeur ne figurera ainsi pas dans les arguments du processus.

Copiez la masterkey dans votre gestionnaire de mots de passe avant le premier démarrage. Elle n’apparaît pas dans un dump de la base de données. Un dump restauré avec une autre masterkey produit donc une instance incapable de lire ses propres secrets. Conservez-la ailleurs que dans l’archive contenant le dump. Ainsi, une sauvegarde volée ne contiendra pas à la fois les données chiffrées et la clé permettant de les déchiffrer.

Définir le domaine externe avant le premier démarrage

ZITADEL_DOMAIN dans .env alimente ZITADEL_EXTERNALDOMAIN dans le conteneur. Il s’agit du nom que vos utilisateurs saisissent. Zitadel en déduit l’issuer OIDC, l’URI de base de l’interface de connexion, les endpoints SAML et l’identifiant de connexion du premier administrateur. Ce paramètre n’est donc pas purement esthétique.

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

Zitadel détermine l’instance à laquelle vous vous adressez à partir de l’en-tête Host. Si cet en-tête ne correspond à aucun domaine connu, toutes les requêtes renvoient la même réponse :

ID=QUERY-1kIjX Message=Instance not found

Vérifiez deux points lorsque cette erreur s’affiche. Soit ZITADEL_DOMAIN ne correspond pas au nom que vous utilisez dans le navigateur, soit un proxy en amont réécrit Host avec l’adresse du serveur upstream. L’erreur se produit également si vous utilisez l’adresse IP du serveur au lieu de son nom.

Vous pouvez modifier ces valeurs ultérieurement. Zitadel doit relancer sa phase de configuration pour prendre la modification en compte, et chaque application déjà enregistrée conserve ses anciennes URI de redirection. Choisir le nom définitif dès maintenant coûte beaucoup moins cher qu’une migration ultérieure.

Terminer TLS avec l’overlay Let's Encrypt

Pour un domaine public, ajoutez l’overlay Let's Encrypt de Zitadel. Il configure Traefik pour utiliser le challenge HTTP ACME (automatic certificate management environment) et remplace les ports publiés par 80 et 443. Aucun autre service du serveur ne doit donc utiliser l’un ou l’autre de ces ports.

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

L’overlay définit également ZITADEL_EXTERNALPORT: 443 et ZITADEL_EXTERNALSECURE: true sur le conteneur API. L’URL publique et les URL que Zitadel génère pour lui-même correspondent ainsi. L’enregistrement A doit déjà résoudre avant le démarrage, car le challenge HTTP échoue sans lui.

Si vous terminez déjà TLS sur nginx ou sur un load balancer, utilisez plutôt docker-compose.mode-external-tls.yml et définissez TRAEFIK_TRUSTED_IPS avec les plages d’adresses utilisées par votre proxy. Traefik n’accepte les en-têtes X-Forwarded-* que lorsqu’ils proviennent d’adresses appartenant à cette liste. L’overlay définit explicitement l’URL externe et les URL de connexion de Zitadel en HTTPS.

Un proxy en amont doit effectuer deux opérations auxquelles Zitadel est particulièrement strict. Il doit utiliser HTTP/2 vers le backend, car l’API utilise gRPC. Il doit également transmettre Host sans modification, ainsi que X-Forwarded-Proto: https. Avec cette stack Compose, la configuration nginx se présente ainsi :

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

Remplacez les placeholders de l’upstream par des adresses accessibles depuis nginx. Si vous servez Zitadel sur un port autre que 443, utilisez grpc_set_header Host $host:$server_port; afin que le port soit transmis avec l’en-tête. Le reste correspond à un virtual host classique. Cette configuration de reverse proxy nginx expliquée ligne par ligne couvre les éléments qui ne sont pas spécifiques à Zitadel.

Le premier compte administrateur et l’obligation de changer le mot de passe

Le premier démarrage crée une instance, une organisation et un compte administrateur humain. Le nom de connexion correspond à zitadel-admin@, suivi de zitadel. et de votre domaine externe. Avec ZITADEL_DOMAIN=auth.example.com, il est donc le suivant :

zitadel-admin@zitadel.auth.example.com

Le mot de passe est Password1!, sauf si vous définissez le vôtre. Par défaut, Zitadel impose un changement lors de la première connexion. Le fichier Compose fourni remplace cette valeur par défaut :

ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: false

Cette ligne est codée en dur dans docker-compose.yml au lieu d’être lue depuis .env. Définissez donc vos propres valeurs dans un petit fichier de surcharge. Appelez-le 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 charge automatiquement docker-compose.override.yml uniquement lorsque vous l’exécutez sans l’option -f. Or toutes les commandes du guide Zitadel indiquent -f, ce qui désactive ce comportement. Plutôt que de répéter une liste d’options qui s’allonge, fixez la liste des fichiers dans .env :

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

Démarrez maintenant le service :

docker compose pull
docker compose up -d --wait

--wait conserve la commande en attente jusqu’à ce que les healthchecks réussissent. Lorsque le conteneur d’API n’atteint jamais cet état, Compose s’arrête avec dependency failed to start: container zitadel-zitadel-api-1 is unhealthy, et docker compose logs zitadel-api en indique la cause. Le conteneur est nommé d’après le projet. Le fichier Compose fourni définit lui-même ce nom avec un name: zitadel au niveau supérieur. Le nom du répertoire n’apparaît donc pas. Lors d’un premier démarrage, la cause est généralement la longueur de la masterkey ou le DSN de la base de données.

Connectez-vous à https://auth.example.com/ui/console, changez le mot de passe, puis activez un second facteur pour ce compte avant de créer quoi que ce soit d’autre. Chaque valeur ZITADEL_FIRSTINSTANCE_* ne s’applique que pendant la création de la première instance. Une fois l’instance créée, leur modification n’a plus aucun effet.

Pourquoi la réinitialisation du mot de passe ne fait rien tant que SMTP ne fonctionne pas

Un identity provider qui ne peut pas envoyer d’e-mails est défaillant d’une manière qui peut rester invisible pendant des semaines. Zitadel envoie des e-mails pour les invitations d’utilisateurs, la vérification des adresses, les liens de réinitialisation du mot de passe, les codes à usage unique et les notifications de revendication de domaine. Si aucun provider SMTP n’est configuré, la Console indique tout de même que l’action est terminée, puis le message est transmis au traitement des notifications sans destination d’envoi. Dans v4.20.0, les notifications utilisent par défaut le mode legacy (LegacyEnabled: true), qui ignore les paramètres MaxAttempts: 3 et MaxTtl: 5m du worker parallèle. Ces valeurs ne décrivent donc pas le comportement par défaut des nouvelles tentatives de notification. Rien n’informe la personne qui attend le lien.

Configurez-le dans la Console, dans les paramètres de l’instance à l’emplacement https://auth.example.com/ui/console/settings. Le formulaire du provider SMTP demande une adresse e-mail d’expéditeur, un nom d’expéditeur, l’hôte et le port, un utilisateur, un mot de passe SMTP et une option TLS. Utilisez le bouton de test de ce formulaire avant d’enregistrer, car il envoie un véritable message : celui-ci arrive ou n’arrive pas. Activez le provider pour que Zitadel l’utilise pour envoyer les e-mails.

Un ensemble correspondant de variables d’environnement existe, ZITADEL_DEFAULTINSTANCE_SMTPCONFIGURATION_SMTP_HOST et ses variables associées. Elles s’appliquent lors de la création d’une instance. Sur une stack déjà en fonctionnement, elles n’ont aucun effet. Pour une instance existante, la Console est donc le bon emplacement.

Deux points concernent l’envoi depuis un VPS, car c’est là que le problème se produit généralement. Vérifiez la politique SMTP sortante de votre provider avant de choisir un relay : DigitalOcean bloque par défaut les ports 25, 465 et 587 sur les Droplets. Le port 587 n’est donc pas une solution universelle. Utilisez un relay authentifié sur un port autorisé par votre provider. Publiez également les enregistrements SPF (sender policy framework) et DKIM (domainkeys identified mail) pour le domaine d’envoi. Sinon, le lien de réinitialisation arrive dans les spams, ce qui ressemble exactement, pour l’utilisateur, à un e-mail qui n’a jamais été envoyé.

Dans v4.20.0, les connexions TLS SMTP sortantes rejettent les chaînes de certificats passant par les autorités de certification intermédiaires eMudhra compromises. Un relay concerné doit utiliser un certificat de remplacement.

Vérifiez le fonctionnement avant d’inviter qui que ce soit. Créez un utilisateur temporaire, demandez une réinitialisation du mot de passe et vérifiez que le message arrive. S’il n’arrive pas, docker compose logs -f zitadel-api indique l’échec SMTP. Le mot de passe SMTP est stocké sous forme chiffrée dans la base de données. C’est une donnée supplémentaire que la masterkey protège pour vous.

Sauvegarder Postgres et la masterkey séparément

Tout ce que Zitadel connaît se trouve dans PostgreSQL. La masterkey permet de le déchiffrer. Sauvegardez ces deux éléments dans deux emplacements différents.

Commencez par créer le 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 correspond au format personnalisé. Il compresse les données à la création du dump, et pg_restore peut ensuite les lire de manière sélective. exec -T désactive le terminal. C’est nécessaire, car cette commande est exécutée par cron sans terminal associé.

Envoyez ensuite ce répertoire hors site avec restic, qui chiffre et déduplique les données :

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 s’exécute une seule fois, le premier jour. Ajoutez le dump et les deux dernières commandes dans /usr/local/bin/zitadel-backup.sh, puis exécutez ce script chaque nuit :

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

Sauvegardez .env ainsi que tous les fichiers Compose que vous utilisez dans git. La masterkey fait exception à toutes ces règles. Stockez-la dans votre gestionnaire de mots de passe et dans un deuxième emplacement qui n’est pas ce repository restic. Une archive contenant à la fois la base de données et sa clé de déchiffrement ne constitue plus une sauvegarde d’un système chiffré.

Une sauvegarde que vous n’avez jamais restaurée reste une hypothèse. Restaurez-la dans une base de données temporaire sur le même serveur et vérifiez son contenu :

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

La présence d’une liste de tables dans le schéma eventstore signifie que le dump est valide. Si une erreur indique que le schéma n’existe pas, le dump ne l’est pas. Vous l’aurez découvert un jour où cela ne vous coûte rien. Le principe général pour sauvegarder et mettre à niveau une stack Compose s’applique ici presque sans modification. Garder la masterkey en dehors de la même archive est le seul aspect spécifique à Zitadel.

Mettre à niveau Zitadel sans perdre l’instance

Une mise à niveau consiste à modifier la version dans .env, puis à exécuter deux commandes :

docker compose pull
docker compose up -d --wait

Comprenez ce que fait la seconde commande avant de l’exécuter sur une instance utilisée pour les connexions. La commande du conteneur est start-from-init. Elle exécute les phases init et setup avant de commencer à servir les requêtes, et la phase setup correspond aux migrations de la base de données. Une modification de version lance donc les migrations de schéma sur votre base de données en production au démarrage du conteneur, sans intervention, tandis que --wait attend un healthcheck. C’est précisément pour cela que le test de restauration présenté plus haut est obligatoire.

Effectuez un dump récent immédiatement avant la mise à niveau. Le dump de la nuit précédente est différent.

Avec v4.20.3, les connexions en cours via un fournisseur d’identité externe doivent être recommencées, et les authorization codes Login V1 non utilisés sont rejetés une fois. Les interfaces de connexion personnalisées ont besoin de la permission session.link pour terminer les requêtes OIDC ou SAML. Accordez ce rôle à leur utilisateur de service avec IAM_LOGIN_CLIENT avant la mise à niveau. L’utilisateur de service Login V2 fourni possède déjà ce rôle. Les vérifications de mots de passe de l’API Session appliquent désormais la politique de connexion de l’organisation de l’utilisateur. Les organisations qui désactivent la connexion par nom d’utilisateur et mot de passe doivent donc rediriger les utilisateurs vers leur fournisseur d’identité.

Ne sautez pas de version majeure. Avant de passer de v3 à v4, utilisez d’abord v3.4.1 ou une version ultérieure. v4 rend les clés web OIDC obligatoires et supprime le mécanisme de signature historique. Si votre instance v3 n’a jamais activé les clés web, les tokens signés avec les anciennes clés historiques ne peuvent plus être vérifiés après la mise à niveau. L’avis technique A-10017 de Zitadel indique que les tokens d’accès JWT et les ID tokens existants peuvent devenir invalides immédiatement et que les utilisateurs peuvent devoir se reconnecter. Pour corriger ce problème, Zitadel recommande de passer par v3.4.1 ou une version ultérieure et de laisser expirer les tokens et les sessions signés avec l’ancien mécanisme avant la mise à niveau, ou d’accepter une période planifiée de reconnexion. Si vous utilisez déjà v3.4.1 ou une version ultérieure et que vous avez attendu depuis l’activation des clés web, l’avis indique qu’aucune action n’est nécessaire.

Surveillez la phase setup avec docker compose logs -f zitadel-api. Les migrations d’un eventstore volumineux prennent plusieurs minutes, et Traefik ne route pas vers l’API tant que son healthcheck n’est pas validé. Le site est donc indisponible pendant cette période. Planifiez-la au lieu de la découvrir au moment de l’opération.

Un rollback ne consiste pas à remettre l’ancien tag. Une fois les migrations exécutées, l’ancien binaire ne comprend pas le schéma qu’il trouve. Revenir en arrière nécessite donc de restaurer le dump. Dès que l’instance contient de vrais utilisateurs, passez à docker-compose.prodlike.yml, l’overlay qui exécute init et setup comme des étapes séparées du démarrage. Une migration devient ainsi une opération que vous déclenchez et surveillez, plutôt qu’un effet secondaire du redémarrage d’un conteneur.

Vers quel endpoint pointer votre nouveau fournisseur d’identité

Dans la Console, créez un projet, puis une application à l’intérieur de celui-ci. Choisissez OIDC pour toute application moderne. Zitadel vous fournit un client ID, un client secret et un document de découverte à l’adresse https://auth.example.com/.well-known/openid-configuration. La plupart des logiciels auto-hébergés qui prennent en charge le single sign-on attendent exactement ces éléments.

De nombreux logiciels ne prennent pas en charge cette fonctionnalité, ou la réservent à une offre payante. Dans le premier cas, placez oauth2-proxy devant l’application pour permettre à Zitadel de protéger n’importe quel service HTTP. Dans le second, la taxe SSO des applications auto-hébergées mérite d’être lue avant de planifier une migration autour d’une fonctionnalité que vous n’avez pas payée.

FAQ

De combien de RAM et de CPU une instance Zitadel auto-hébergée a-t-elle besoin ?

Le guide de production de Zitadel indique que Zitadel lui-même nécessite environ 0.5 Go de RAM et peut fonctionner avec moins d’un cœur CPU. Il recommande de conserver 4 cœurs disponibles pour le hachage des mots de passe. Les ressources PostgreSQL sont comptabilisées séparément, à raison d’environ un cœur pour 100 requêtes par seconde et de 4 Go de RAM par cœur. Les valeurs plus élevées du guide correspondent à chaque nœud d’un cluster haute disponibilité à trois nœuds : 4 cœurs et 16 Go chacun, ou environ 4 cœurs et 8 Go sans collecte des journaux ni des métriques. Le quickstart Compose demande au moins 2 Go, ce qui suffit pour faire un essai, mais laisse peu de marge pour la base de données dont les autres services du système auront besoin.

Que se passe-t-il si je perds la masterkey de Zitadel ?

Tout ce qui a été chiffré avec cette clé reste chiffré. Les identifiants des fournisseurs d’identité, le mot de passe SMTP et les seeds des mots de passe à usage unique ne peuvent pas être déchiffrés, et la clé ne peut pas être modifiée a posteriori. Un dump de la base de données ne suffit pas à restaurer une instance fonctionnelle, car il contient le texte chiffré, mais aucune clé. Stockez la masterkey dans un gestionnaire de mots de passe, à un emplacement distinct de la sauvegarde qui contient le dump. Si les deux sont perdus, il ne reste qu’à reconstruire l’instance depuis zéro.

Pourquoi les e-mails de réinitialisation du mot de passe Zitadel n’arrivent-ils jamais ?

Parce qu’aucun fournisseur SMTP n’est configuré, ou parce que celui qui est configuré ne peut pas remettre les messages. Zitadel v4.20.0 utilise par défaut le traitement historique des notifications. Les paramètres de trois tentatives et de cinq minutes du worker parallèle sont donc ignorés. Configurez le fournisseur SMTP dans les paramètres de l’instance et utilisez le bouton de test de ce formulaire. Il envoie un véritable message. Activez le fournisseur, utilisez un relay authentifié sur un port autorisé par votre fournisseur de VPS et publiez les enregistrements SPF et DKIM du domaine d’envoi afin que le message ne soit pas filtré comme spam.

Puis-je modifier le domaine externe de Zitadel après l’installation ?

Oui, mais pas en modifiant uniquement .env. Modifiez ZITADEL_EXTERNALDOMAIN, ZITADEL_EXTERNALPORT et ZITADEL_EXTERNALSECURE, puis laissez Zitadel réexécuter sa phase de configuration afin qu’il prenne la modification en compte. Les applications déjà enregistrées conservent leurs anciennes URI de redirection et doivent être mises à jour manuellement. Toute requête dont l’en-tête Host ne correspond pas à un domaine connu de Zitadel reçoit Instance not found. Choisir le nom définitif avant le premier démarrage évite tous ces problèmes.

Cet article vous a-t-il été utile ?