Installare Zitadel su VPS con Docker
Zitadel richiede circa 512 MB di RAM. Configura PostgreSQL, masterkey, TLS, SMTP e backup su un VPS e verifica cosa cambia nel database dopo un upgrade.
Cosa serve per eseguire Zitadel in self-hosting su un VPS
Per eseguire Zitadel in self-hosting su un VPS servono un host Docker, un nome DNS pubblico che punti al server, PostgreSQL e CPU e RAM sufficienti per entrambi. La guida di produzione di Zitadel stima per l'applicazione circa 512 MB di RAM e meno di un core CPU. Il consumo che cresce maggiormente dipende dal database e dall'hashing delle password. Zitadel è un identity provider. Emette token tramite OIDC (OpenID Connect) e SAML (security assertion markup language), così gli altri servizi non devono più mantenere elenchi utenti separati. L'installazione consiste in un curl e in un docker compose up. I componenti che determinano la stabilità dell'istanza sono la masterkey, l'utente del database, SMTP (simple mail transfer protocol), il backup e il primo aggiornamento.
Tutto ciò che segue presuppone Ubuntu 24.04, Docker Engine 24 o versione successiva con il plugin Compose versione 2.24.4 o successiva e un nome come auth.example.com già risolto verso il server. Gli overlay TLS usano !override, che richiede quella versione di Compose.
Quanta capacità VPS richiede Zitadel?
Il quickstart Compose nella documentazione di Zitadel richiede 2 GB di RAM. Questo valore si riferisce al quickstart. La guida di produzione di Zitadel indica valori diversi.
I dati alla base di questo grafico
[
{
"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
}
]Si tratta di raccomandazioni pubblicate, non di misurazioni effettuate su un server in esecuzione. Consideratele come indicazioni sulle dimensioni del problema. Il processo di Zitadel, da solo, è leggero: la guida lo quantifica in circa 0.5 GB di RAM e indica che può funzionare con meno di un core CPU. I core servono per l'hashing delle password, che è volutamente lento. Per questo un picco di accessi genera un picco di utilizzo della CPU e la guida raccomanda di mantenere disponibili 4 core CPU. PostgreSQL rappresenta l'altra componente del dimensionamento: la stessa guida calcola circa un core ogni 100 richieste al secondo e 4 GB di RAM per core.
Le due righe con i valori maggiori non si riferiscono a un singolo server. Per una configurazione minima ad alta disponibilità, la guida raccomanda un cluster di tre nodi, ciascuno con 4 core e 16 GB. Indica inoltre che è possibile ridurre questi valori a circa 4 core e 8 GB per nodo, se si escludono la raccolta dei log e le metriche. Non indica alcun dimensionamento per un singolo nodo.
Quindi un VPS da 2 GB avvierà questo stack, ma è molto al di sotto del valore che la guida prevede per il solo database quando arriverà traffico reale. Il login è il servizio da cui dipendono tutti gli altri servizi. Quando è inattivo, nessun servizio che si fida di esso consente l'accesso. Decidere che il budget previsto dalla guida per database e hashing è superiore a quanto si desidera spendere per l'autenticazione è una scelta ragionevole. È inoltre molto meno costoso farla ora che dopo una migrazione. Il confronto tra Keycloak, Authentik e Zitadel illustra i costi di ciascuna soluzione in termini di memoria e attività operative, mentre un server Authentik self-hosted è solitamente la scelta per un server più piccolo.
Ottenere lo stack e bloccare una versione
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 .envQuel file definisce quattro servizi che verranno effettivamente eseguiti. Traefik è il reverse proxy: instrada in base al percorso e, con l'overlay più avanti, termina TLS (transport layer security). zitadel-api è il binario Go in ascolto sulla porta 8080. zitadel-login è l'interfaccia di accesso pubblicata su /ui/v2/login. postgres contiene tutti i dati. Nello stesso file sono presenti anche una cache Redis e un collector OpenTelemetry, disattivati tramite i profili Compose finché non li abiliti.
Non eseguire ancora docker compose up. Il primo avvio crea l'istanza e diverse impostazioni riportate più avanti non possono essere modificate successivamente senza attività aggiuntive.
Il .env copiato blocca i propri tag delle immagini:
ZITADEL_VERSION=v4.16.0
TRAEFIK_IMAGE=traefik:v3.7.7
POSTGRES_IMAGE=postgres:17.10-alpineLa release v4 attuale è v4.20.3, pubblicata il 13 novembre 2026, quattro versioni minor più avanti rispetto alla versione bloccata nel file distribuito. La release precedente alla v4.20.0, v4.19.5 del 15 ottobre 2026, è la prima interessata dall'avviso tecnico A-10018 di Zitadel: gli endpoint per gli elenchi nelle API v1 e v2 applicano ora limiti predefiniti e massimi, quindi un client che esegue un elenco senza specificare un limite non riceve più tutti i risultati e deve usare la paginazione; una richiesta che supera il limite massimo viene rifiutata. Tutte le release successive, inclusa la v4.20.0, includono questa modifica. Imposta ZITADEL_VERSION sulla versione che vuoi eseguire e resta sulla linea v4 invece di seguire sempre la versione più recente. Ignora v4.18.0 se scegli manualmente una versione: le note di release indicano che in quella versione la procedura di setup non funziona e specificano di usare invece la v4.19.0. Il curl precedente scarica docker-compose.yml dal ramo main, che non è bloccato su alcuna versione; quindi salva entrambe le copie dei file in un repository git. In caso contrario, lo stesso comando eseguito su un nuovo server il mese prossimo produrrà un file diverso e non saprai che cosa è cambiato.
Sostituisci LOGIN_SESSION_COOKIE_SECRET in .env con un valore casuale generato da openssl rand -base64 32. La Login UI lo usa per firmare i cookie di sessione e le note di release della v4.19.5 avvertono esplicitamente di non mantenere il valore di esempio.
Assegnare a Postgres un utente dedicato e una password reale
Il .env fornito collega Zitadel a PostgreSQL usando l'utente superuser, con la password postgres:
POSTGRES_ADMIN_USER=postgres
POSTGRES_ADMIN_PASSWORD=postgres
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://postgres:postgres@postgres:5432/zitadel?sslmode=disableIn questa fase di hardening c'è un problema insidioso. La documentazione di Zitadel indica di aggiungere POSTGRES_ZITADEL_PASSWORD a .env, ma il docker-compose.yml di base non legge mai quella variabile. Impostarla, quindi, non produce alcun effetto. Modificare solo POSTGRES_ADMIN_PASSWORD interrompe invece la connessione, perché la password è scritta anche direttamente nella stringa DSN (data source name). La DSN determina il modo in cui Zitadel si connette.
I commenti in .env.example spiegano chiaramente il comportamento restante: quando è configurata una DSN, Zitadel usa direttamente quell'utente e non ne crea automaticamente uno senza privilegi. Il ruolo deve quindi esistere prima del primo avvio. Genera una password per il ruolo, imposta POSTGRES_ADMIN_PASSWORD su una password casuale distinta in .env prima di avviare Postgres, quindi avvia Postgres separatamente e crea il ruolo. L'immagine Postgres applica la password amministrativa solo quando inizializza una directory dati vuota; modificare .env in seguito non aggiorna la password di un database già esistente.
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;
SQLLe chiamate psql vengono eseguite all'interno del container tramite il socket locale, considerato attendibile dall'immagine ufficiale di Postgres. Per questo non richiedono una password. L'aspetto importante è la proprietà. La fase di inizializzazione di Zitadel crea i propri schemi (eventstore, projections, system) e le relative tabelle. La proprietà del database assegna al ruolo il privilegio CREATE necessario per inizializzare questi schemi. La modifica introdotta in PostgreSQL 15 sui permessi CREATE dello schema public è separata e non implica che l'inizializzazione degli schemi di Zitadel non riesca.
Ora configura la DSN per usare il nuovo ruolo e conserva la password amministrativa impostata prima dell'avvio di Postgres:
POSTGRES_ADMIN_PASSWORD=a-32-character-random-string
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://zitadel:the-password-you-generated@postgres:5432/zitadel?sslmode=disablesslmode=disable lascia non cifrata la connessione al database sulla rete Compose privata; la relativa porta non viene mai pubblicata sull'host. La guida di Zitadel per i database consiglia TLS per le connessioni ai database in produzione. Dopo il primo avvio completo, verifica che il ruolo sia effettivamente proprietario dei propri dati:
docker compose exec -T postgres psql -U zitadel -d zitadel -c '\dn'L'output dovrebbe elencare uno schema eventstore, uno schema projections e uno schema system. Se questi schemi mancano, la fase di inizializzazione non è arrivata a questo punto e il log del container API indicherà il motivo.
La masterkey e il costo della sua perdita
Zitadel cifra i secret prima di archiviarli: credenziali dell’identity provider, password SMTP, seed per le password monouso e chiavi delle macchine. La masterkey sblocca tutti questi dati. È composta esattamente da 32 byte e la documentazione è chiara sulle conseguenze: non può essere modificata senza perdere l’accesso ai dati cifrati.
Generane una e sostituisci la riga segnaposto in .env:
tr -dc A-Za-z0-9 </dev/urandom | head -c 32; echoModifica la riga ZITADEL_MASTERKEY=MasterkeyNeedsToHave32Characters invece di aggiungerne una seconda. Compose usa l’ultima definizione di una chiave ripetuta, quindi l’aggiunta funziona, ma un file con due righe masterkey può creare problemi a chi dovrà leggerlo in seguito.
Considera ora dove viene conservata la chiave. Il file Compose avvia il container API in questo modo:
command: start-from-init --masterkey "${ZITADEL_MASTERKEY}"La masterkey si trova quindi nella riga di comando del container, dove docker inspect la mostra a chiunque possa raggiungere il socket Docker. Su un VPS gestito da un solo amministratore, questo compromesso è accettabile, mentre la modalità impostata su .env protegge la chiave sul disco. Se non è accettabile, monta la chiave come file e usa invece --masterkeyFile /run/secrets/zitadel-masterkey, che mantiene il valore fuori dagli argomenti del processo.
Copia la masterkey nel password manager prima del primo avvio. Non compare in un dump del database, quindi un dump ripristinato usando una masterkey diversa produce un’istanza che non riesce a leggere i propri secret. Conservala in un luogo diverso dall’archivio che contiene il dump, così un singolo backup sottratto non conterrà sia i dati cifrati sia la chiave per decifrarli.
Impostare il dominio esterno prima del primo avvio
ZITADEL_DOMAIN in .env alimenta ZITADEL_EXTERNALDOMAIN nel container. È il nome che gli utenti digitano. Zitadel ricava da questo valore l'issuer OIDC, l'URI di base dell'interfaccia di accesso, gli endpoint SAML e il nome di accesso del primo amministratore. Non è quindi un valore puramente descrittivo.
ZITADEL_DOMAIN=auth.example.com
ZITADEL_EXTERNALPORT=443
ZITADEL_EXTERNALSECURE=trueZitadel determina l'istanza a cui vi state collegando dall'header Host. Se l'header non corrisponde a un dominio riconosciuto, ogni richiesta restituisce la stessa risposta:
ID=QUERY-1kIjX Message=Instance not foundQuando visualizzate questo errore, controllate due elementi. ZITADEL_DOMAIN potrebbe non corrispondere al nome che state utilizzando per la navigazione, oppure un proxy a monte potrebbe riscrivere Host con l'indirizzo dell'upstream. L'errore compare anche quando accedete all'indirizzo IP del server invece che al nome.
Potete modificare questi valori in seguito. Zitadel deve eseguire nuovamente la fase di configurazione per applicare la modifica, mentre ogni applicazione già registrata conserva i propri URI di redirect precedenti. Scegliere ora il nome definitivo è molto più semplice che cambiarlo in seguito.
Terminare TLS con l'overlay Let's Encrypt
Per un dominio pubblico, aggiungi l'overlay Let's Encrypt di Zitadel. Imposta Traefik per usare la challenge HTTP di ACME (ambiente per la gestione automatica dei certificati) e sostituisce le porte pubblicate con 80 e 443. Nessun altro processo sul server può quindi occupare una di queste porte.
curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/docker-compose.mode-letsencrypt.yml
echo 'LETSENCRYPT_EMAIL=ops@example.com' >> .envL'overlay imposta anche ZITADEL_EXTERNALPORT: 443 e ZITADEL_EXTERNALSECURE: true sul container API. Per questo l'URL pubblico e gli URL generati da Zitadel coincidono. Il record A deve risolvere prima dell'avvio, perché la challenge HTTP non funziona senza di esso.
Se termini già TLS su nginx o su un load balancer, usa invece docker-compose.mode-external-tls.yml e imposta TRAEFIK_TRUSTED_IPS sugli intervalli di indirizzi dai quali il proxy invia le richieste. Traefik considera gli header X-Forwarded-* solo se provengono da indirizzi inclusi nell'elenco. L'overlay imposta esplicitamente su HTTPS l'URL esterno di Zitadel e gli URL di accesso.
Un proxy upstream deve svolgere due funzioni che Zitadel verifica rigorosamente. Deve usare HTTP/2 verso il backend, perché l'API usa gRPC. Deve inoltre inoltrare Host senza modificarlo, insieme a X-Forwarded-Proto: https. Con questo stack Compose, la configurazione nginx ha questa struttura:
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;
}
}Sostituisci i segnaposto dell'upstream con indirizzi raggiungibili da nginx. Se pubblichi Zitadel su una porta diversa da 443, usa grpc_set_header Host $host:$server_port; per includere la porta nell'header. Il resto è un normale virtual host; una configurazione di reverse proxy nginx spiegata riga per riga illustra le parti non specifiche di Zitadel.
Il primo amministratore e l'obbligo di cambiare la password
Il primo avvio crea una istanza, una organizzazione e un amministratore umano. Il nome di accesso è zitadel-admin@ più zitadel. più il dominio esterno, quindi con ZITADEL_DOMAIN=auth.example.com è:
zitadel-admin@zitadel.auth.example.comLa password è Password1!, a meno che non ne imposti una personalizzata. Il valore predefinito upstream di Zitadel obbliga a cambiarla al primo accesso, mentre il file Compose fornito sostituisce questo comportamento:
ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: falseQuella riga è codificata direttamente in docker-compose.yml, invece di essere letta da .env. Inserisci quindi i tuoi valori in un piccolo overlay separato. Chiamalo 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 carica automaticamente docker-compose.override.yml solo quando lo esegui senza il flag -f, mentre tutti i comandi della guida di Zitadel passano -f, disattivando questo comportamento. Invece di ripetere un elenco di flag sempre più lungo, fissa l'elenco dei file in .env:
COMPOSE_FILE=docker-compose.yml:docker-compose.mode-letsencrypt.yml:docker-compose.local.ymlOra avvialo:
docker compose pull
docker compose up -d --wait--wait mantiene il comando in attesa finché gli healthcheck non hanno esito positivo. Se il container API non raggiunge mai quello stato, Compose si interrompe con dependency failed to start: container zitadel-zitadel-api-1 is unhealthy e docker compose logs zitadel-api contiene il motivo. Il container prende il nome dal progetto e il file Compose fornito lo imposta direttamente con un name: zitadel di livello superiore, quindi il nome della directory non compare. Al primo avvio, il motivo è solitamente la lunghezza della masterkey o il DSN del database.
Accedi a https://auth.example.com/ui/console, cambia la password, quindi abilita un secondo fattore per quell'account prima di creare qualsiasi altro elemento. Ogni valore ZITADEL_FIRSTINSTANCE_* viene applicato soltanto durante la creazione della prima istanza. Dopo la creazione dell'istanza, modificarli non produce alcun effetto.
Perché la reimpostazione della password non fa nulla finché SMTP non funziona
Un identity provider che non riesce a inviare email è guasto in un modo che può restare nascosto per settimane. Zitadel invia email per gli inviti degli utenti, la verifica degli indirizzi, i link per la reimpostazione della password, i codici monouso e le notifiche di rivendicazione dei domini. Se non è configurato alcun provider SMTP, la Console segnala comunque l'operazione come completata e il messaggio passa alla gestione delle notifiche senza una destinazione a cui essere inviato. In v4.20.0, le notifiche usano per impostazione predefinita la modalità legacy (LegacyEnabled: true), che ignora le impostazioni MaxAttempts: 3 e MaxTtl: 5m del worker parallelo. Questi valori non descrivono il comportamento predefinito dei nuovi tentativi di invio delle notifiche. La persona in attesa del link non riceve alcuna informazione.
Configurare SMTP nella Console, nelle impostazioni dell'istanza all'indirizzo https://auth.example.com/ui/console/settings. Il modulo del provider SMTP richiede l'indirizzo email del mittente, il nome del mittente, host e porta, un utente, una password SMTP e un'opzione per TLS. Usare il pulsante di test nel modulo prima di salvare, perché invia un messaggio reale: il messaggio arriva oppure non arriva. Attivare il provider affinché Zitadel lo utilizzi per inviare le email.
È disponibile un insieme corrispondente di variabili d'ambiente, ZITADEL_DEFAULTINSTANCE_SMTPCONFIGURATION_SMTP_HOST e le variabili correlate. Queste variabili vengono applicate quando si crea un'istanza. In uno stack già in esecuzione non hanno effetto, quindi per un'istanza esistente è preferibile usare la Console.
Per l'invio da un VPS occorre considerare due aspetti, perché è qui che il problema si verifica più spesso. Verificare la policy del provider per il traffico SMTP in uscita prima di scegliere un relay: DigitalOcean blocca per impostazione predefinita le porte 25, 465 e 587 sui Droplet, quindi la porta 587 non è una soluzione universale. Usare un relay autenticato su una porta consentita dal provider. Pubblicare inoltre record SPF (sender policy framework) e DKIM (domainkeys identified mail) per il dominio mittente. In caso contrario, il link per la reimpostazione finisce nello spam e all'utente appare esattamente come se l'email non fosse mai stata inviata.
In v4.20.0, le connessioni TLS SMTP in uscita rifiutano le catene di certificati che passano dalle CA intermedie eMudhra compromesse. Il relay interessato richiede un certificato sostitutivo.
Verificare il funzionamento prima di invitare qualcuno. Creare un utente temporaneo, richiedere la reimpostazione della password e verificare che il messaggio arrivi. Se non arriva, docker compose logs -f zitadel-api identifica il problema SMTP. La password SMTP viene memorizzata in forma cifrata nel database. È un altro elemento che il masterkey protegge per conto dell'utente.
Esegui separatamente il backup di Postgres e della masterkey
Tutti i dati che Zitadel conosce si trovano in PostgreSQL. La masterkey serve a decrittografarli. Esegui il backup in due posizioni diverse.
Prima crea il 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 indica il formato personalizzato, che comprime i dati durante l'esportazione e che pg_restore può leggere in modo selettivo. exec -T disabilita il terminale. Questo è importante perché il comando viene eseguito da cron senza un terminale associato.
Poi trasferisci la directory fuori sede con restic, che esegue la crittografia e la deduplicazione:
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 viene eseguito una sola volta, esclusivamente il primo giorno. Inserisci il dump e gli ultimi due comandi in /usr/local/bin/zitadel-backup.sh ed eseguilo ogni notte:
0 3 * * * /usr/local/bin/zitadel-backup.shEsegui il backup di .env e di ogni file Compose utilizzato, salvandoli in git. La masterkey è l'unica eccezione. Deve essere archiviata nel password manager e in una seconda posizione che non sia questo repository restic. Un archivio che contiene insieme il database e la relativa chiave di decrittografia non costituisce infatti un backup di un sistema crittografato.
Un backup che non hai mai ripristinato è solo un'ipotesi. Ripristinalo in un database temporaneo sullo stesso server e controllalo:
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_testLa presenza di un elenco di tabelle nello schema eventstore indica che il dump è valido. Un errore che segnala l'assenza dello schema indica invece che il dump non è valido. Puoi così scoprirlo in un momento in cui la verifica non comporta alcun costo. Il modello generale per eseguire il backup e aggiornare uno stack Compose si applica qui quasi senza modifiche. L'unico aspetto specifico di Zitadel consiste nel mantenere la masterkey fuori dallo stesso archivio.
Aggiornare Zitadel senza perdere l'istanza
Un aggiornamento consiste nell'incrementare la versione in .env e poi eseguire due comandi:
docker compose pull
docker compose up -d --waitPrima di eseguire il secondo comando su un'istanza usata per gli accessi degli utenti, è necessario comprenderne il comportamento. Il comando del container è start-from-init: esegue le fasi di init e setup prima di iniziare a servire le richieste, e la fase di setup esegue le migrazioni del database. Di conseguenza, un incremento di versione esegue migrazioni dello schema sul database in produzione all'avvio del container, senza intervento dell'operatore, mentre --wait rimane in attesa di un healthcheck. È proprio per questo che il test di ripristino precedente non è facoltativo.
Esegui un dump aggiornato subito prima dell'aggiornamento. Il dump della notte precedente è un'altra cosa.
Con la v4.20.3, gli accessi in corso tramite identity provider esterni devono essere riavviati e i codici di autorizzazione Login V1 non ancora riscattati vengono rifiutati una volta. Le Login UI personalizzate richiedono il permesso session.link per completare le richieste OIDC o SAML; assegna quel ruolo al relativo service user tramite IAM_LOGIN_CLIENT prima dell'aggiornamento. Il service user distribuito per Login V2 dispone già di quel ruolo. I controlli delle password dell'API Session ora applicano la policy di accesso dell'organizzazione dell'utente, quindi le organizzazioni che disabilitano l'accesso tramite nome utente e password devono indirizzare gli utenti al proprio identity provider.
Non saltare una versione major. Prima di passare dalla v3 alla v4, aggiorna almeno alla v3.4.1. La v4 rende obbligatorie le web key OIDC e rimuove il percorso di firma legacy; quindi, se l'istanza v3 non ha mai abilitato le web key, dopo l'aggiornamento i token firmati con le vecchie chiavi legacy non saranno più verificabili. L'avviso tecnico A-10017 di Zitadel indica che i token di accesso JWT e i token ID esistenti possono diventare immediatamente non validi e che gli utenti potrebbero dover eseguire nuovamente l'accesso. La soluzione indicata consiste nel passare prima alla v3.4.1 o a una versione successiva e attendere la scadenza dei token e delle sessioni firmati con il metodo legacy prima dell'aggiornamento, oppure accettare una finestra pianificata per il nuovo accesso. Se esegui già la v3.4.1 o una versione successiva e hai atteso da quando sono state abilitate le web key, l'avviso indica che non è necessaria alcuna azione.
Monitora la fase di setup con docker compose logs -f zitadel-api. Le migrazioni di un eventstore di grandi dimensioni richiedono alcuni minuti e Traefik non instrada le richieste verso l'API finché l'healthcheck non ha esito positivo; di conseguenza, il sito rimane non disponibile durante quella finestra. Pianifica questa interruzione invece di scoprirla durante l'aggiornamento.
Il rollback non consiste nel ripristinare il vecchio tag. Dopo l'esecuzione delle migrazioni, il binario precedente non riconosce lo schema trovato; quindi il rollback richiede il ripristino del dump. Quando l'istanza contiene utenti reali, passa a docker-compose.prodlike.yml, l'overlay che esegue init e setup come fasi separate dall'avvio, così una migrazione diventa un'operazione che avvii e monitori, invece di un effetto collaterale del riavvio di un container.
A cosa puntare con il nuovo identity provider
Nella Console, crea un progetto e quindi un’applicazione al suo interno. Scegli OIDC per qualsiasi applicazione moderna: Zitadel fornisce un client ID, un client secret e un documento di discovery all’indirizzo https://auth.example.com/.well-known/openid-configuration. La maggior parte dei software self-hosted che supportano il single sign-on richiede esattamente questi elementi.
Molti software non lo supportano oppure lo rendono disponibile soltanto in un piano a pagamento. Nel primo caso, oauth2-proxy davanti all’applicazione trasforma qualsiasi servizio HTTP in un servizio che Zitadel può proteggere. Nel secondo, vale la pena leggere il costo del SSO nelle applicazioni self-hosted prima di pianificare una migrazione basata su una funzionalità per cui non hai acquistato una licenza.
FAQ
Quanta RAM e CPU richiede Zitadel in hosting autonomo?
La guida di produzione di Zitadel indica che il solo Zitadel richiede circa 0.5 GB di RAM e può funzionare con meno di un core CPU. Raccomanda inoltre di mantenere disponibili 4 core per l'hashing delle password. PostgreSQL viene dimensionato separatamente, con circa un core ogni 100 richieste al secondo e 4 GB di RAM per core. I valori più elevati indicati nella guida si riferiscono a ogni nodo di un cluster a disponibilità elevata composto da tre nodi: 4 core e 16 GB per nodo, oppure circa 4 core e 8 GB senza raccolta dei log e delle metriche. La procedura rapida con Compose richiede almeno 2 GB, una quantità sufficiente per provarlo, ma che lascia poco spazio al database necessario agli altri servizi del sistema.
Cosa succede se perdo la masterkey di Zitadel?
Tutto ciò che è stato cifrato con la masterkey resta cifrato. Le credenziali dei provider di identità, la password SMTP e i seed per le password monouso non possono essere decifrati, e la chiave non può essere sostituita in un secondo momento. Un dump del database, da solo, non ripristina un'istanza funzionante, perché contiene il ciphertext ma non la chiave. Conserva la masterkey in un password manager e in un luogo separato dal backup che contiene il dump. Se vengono persi entrambi, l'unica possibilità è ricreare l'istanza da zero.
Perché le email di reimpostazione della password di Zitadel non arrivano mai?
Perché non è configurato alcun provider SMTP oppure il provider configurato non riesce a consegnare i messaggi. Zitadel v4.20.0 usa per impostazione predefinita l'elaborazione legacy delle notifiche, quindi le impostazioni del worker parallelo relative ai tre tentativi e ai cinque minuti vengono ignorate. Configura il provider SMTP nelle impostazioni dell'istanza e usa il pulsante di test presente nel modulo: invia un messaggio reale. Attiva il provider, usa un relay autenticato su una porta consentita dal provider VPS e pubblica i record SPF e DKIM per il dominio mittente, in modo che il messaggio non venga filtrato come spam.
Posso modificare il dominio esterno di Zitadel dopo l'installazione?
Sì, ma non modificando soltanto .env. Modifica ZITADEL_EXTERNALDOMAIN, ZITADEL_EXTERNALPORT e ZITADEL_EXTERNALSECURE, quindi consenti a Zitadel di eseguire nuovamente la fase di setup, così da applicare la modifica. Le applicazioni già registrate mantengono i vecchi URI di redirect e devono essere aggiornate manualmente. Inoltre, qualsiasi richiesta il cui header Host non corrisponda a un dominio noto a Zitadel riceve in risposta Instance not found. Scegliere il nome definitivo prima del primo avvio evita tutti questi problemi.