Cómo alojar Zitadel en un VPS con Docker
Zitadel necesita unos 512 MB de RAM. Configura PostgreSQL, masterkey, TLS, SMTP y copias de seguridad en un VPS, y comprueba qué cambia al actualizar la base de datos.
Qué necesita para alojar Zitadel en un VPS
Para alojar Zitadel en un VPS necesita un host Docker, un nombre DNS público que apunte a él, PostgreSQL y suficiente CPU y RAM para ambos. La guía de producción de Zitadel asigna a la aplicación unos 512 MB de RAM y menos de un núcleo de CPU. La base de datos y el hash de contraseñas son los componentes que más crecen. Zitadel es un proveedor de identidad. Emite tokens mediante OIDC (OpenID Connect) y SAML (security assertion markup language), de modo que los demás servicios no necesitan mantener sus propias listas de usuarios. La instalación consiste en un curl y un docker compose up. Los elementos que determinan si sobrevive son la masterkey, el usuario de la base de datos, SMTP (simple mail transfer protocol), la copia de seguridad y la primera actualización.
Todo lo siguiente presupone Ubuntu 24.04, Docker Engine 24 o posterior con el complemento Compose versión 2.24.4 o posterior, y un nombre como auth.example.com que ya resuelva hacia el servidor. Las superposiciones TLS utilizan !override, que requiere esa versión de Compose.
¿Cuántos recursos de VPS necesita Zitadel?
El inicio rápido con Compose de la documentación de Zitadel pide 2 GB de RAM. Esa cifra corresponde al inicio rápido. La guía de producción de Zitadel publica valores diferentes.
Los datos de este gráfico
[
{
"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
}
]Son recomendaciones publicadas, no mediciones tomadas en un servidor en funcionamiento. Debe interpretarlas como una descripción de las necesidades del sistema. El proceso de Zitadel es pequeño: la guía lo sitúa en aproximadamente 0.5 GB de RAM y afirma que puede ejecutarse con menos de un núcleo de CPU. Los núcleos adicionales se destinan al cálculo de hashes de contraseñas, que es deliberadamente lento. Por eso, un pico de inicios de sesión se convierte en un pico de CPU, y la guía recomienda mantener disponibles 4 núcleos de CPU. PostgreSQL representa la otra parte del consumo: la misma guía calcula aproximadamente un núcleo por cada 100 solicitudes por segundo y 4 GB de RAM por núcleo.
Las dos filas de mayor tamaño no corresponden a un solo servidor. Para una configuración mínima de alta disponibilidad, la guía recomienda un clúster de tres nodos, cada uno con 4 núcleos y 16 GB, y afirma que puede reducirse a aproximadamente 4 núcleos y 8 GB por nodo si se omiten la recopilación de registros y las métricas. No indica valores de dimensionamiento para un solo nodo.
Por tanto, un VPS con 2 GB iniciará esta pila, pero queda muy por debajo de lo que la guía asigna únicamente a la base de datos cuando llegue tráfico real. El inicio de sesión es el servicio del que dependen todos los demás servicios. Cuando deja de funcionar, ningún servicio que confíe en él permite el acceso. Decidir que el presupuesto de la guía para la base de datos y el cálculo de hashes supera lo que quiere gastar en autenticación es una decisión razonable. También es mucho más barato tomarla ahora que después de una migración. La comparación de Keycloak, Authentik y Zitadel explica cuánto consume cada opción en memoria y en trabajo operativo, y un servidor Authentik autogestionado suele ser la respuesta en un servidor más pequeño.
Obtenga la pila y fije una versión
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 .envEse archivo define cuatro servicios que ejecutará realmente. Traefik es el reverse proxy: enruta por ruta y, con la superposición que aparece más abajo, termina TLS (transport layer security). zitadel-api es el binario Go en el puerto 8080. zitadel-login es la interfaz de inicio de sesión disponible en /ui/v2/login. postgres contiene todo. Una caché Redis y un colector OpenTelemetry están en el mismo archivo detrás de perfiles de Compose y permanecen desactivados hasta que los solicite.
Todavía no ejecute docker compose up. El primer arranque crea la instancia, y varios ajustes de las secciones siguientes no se pueden cambiar después sin trabajo adicional.
El .env que copió fija sus propias etiquetas de imagen:
ZITADEL_VERSION=v4.16.0
TRAEFIK_IMAGE=traefik:v3.7.7
POSTGRES_IMAGE=postgres:17.10-alpineLa versión v4 actual es v4.20.3, publicada el 13 de noviembre de 2026, cuatro versiones menores por delante de la versión fijada en el archivo distribuido. La versión anterior a v4.20.0, v4.19.5, del 15 de octubre de 2026, es la primera cubierta por el aviso técnico A-10018 de Zitadel: los endpoints de listado afectados de las API v1 y v2 aplican ahora límites predeterminados y máximos, por lo que un cliente que lista sin indicar un límite ya no obtiene todos los resultados y debe paginar, y una solicitud que pide más que el máximo se rechaza. Todas las versiones posteriores, incluida v4.20.0, incorporan ese cambio. Establezca ZITADEL_VERSION en la versión que pretende ejecutar y manténgase en la línea v4, en lugar de seguir siempre la versión más reciente. Omita v4.18.0 si elige manualmente una versión: sus notas de la versión indican que el paso de configuración falla en esa versión y recomiendan usar v4.19.0. El curl anterior obtiene docker-compose.yml de la rama main, que no está fijada a ningún commit, así que confirme copias de ambos archivos en un repositorio git. De lo contrario, el mismo comando en un equipo nuevo el mes próximo le entregará un archivo diferente y no sabrá qué cambió.
Sustituya LOGIN_SESSION_COOKIE_SECRET en .env por un valor aleatorio generado mediante openssl rand -base64 32. Login UI lo utiliza para firmar las cookies de sesión, y las notas de la versión v4.19.5 advierten explícitamente que no se debe conservar el valor de ejemplo.
Asigne a usuario propio y una contraseña real a Postgres
El archivo .env incluido conecta Zitadel con PostgreSQL como superusuario, con la contraseña postgres:
POSTGRES_ADMIN_USER=postgres
POSTGRES_ADMIN_PASSWORD=postgres
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://postgres:postgres@postgres:5432/zitadel?sslmode=disableAquí hay una trampa en el paso de refuerzo de seguridad. La documentación de Zitadel indica que se debe añadir POSTGRES_ZITADEL_PASSWORD a .env, pero el archivo base docker-compose.yml nunca lee esa variable, por lo que definirla no cambia nada. Cambiar sólo POSTGRES_ADMIN_PASSWORD rompe la conexión, porque la contraseña también está escrita literalmente dentro de la cadena DSN (nombre de origen de datos). La DSN es la línea que determina cómo se conecta Zitadel.
Los comentarios de .env.example lo indican claramente: cuando se configura una DSN, Zitadel usa directamente ese usuario y no crea uno sin privilegios, por lo que el rol debe existir antes del primer arranque. Genere una contraseña para el rol, establezca POSTGRES_ADMIN_PASSWORD con una contraseña aleatoria distinta en .env antes de iniciar Postgres, inicie Postgres por separado y cree el rol. La imagen de Postgres sólo aplica esa contraseña de administrador cuando inicializa un directorio de datos vacío; cambiar .env después no cambia la contraseña de una base de datos existente.
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;
SQLEsas llamadas a psql se ejecutan dentro del contenedor mediante su socket local, en el que la imagen oficial de Postgres confía, por lo que no solicitan una contraseña. Lo importante es la propiedad. La fase de inicialización de Zitadel crea sus propios esquemas (eventstore, projections, system) y tablas. La propiedad de la base de datos concede al rol el privilegio CREATE necesario para inicializar esos esquemas. El cambio de PostgreSQL 15 en los permisos CREATE del esquema public es independiente y no implica que falle la inicialización de esquemas de Zitadel.
Ahora apunte la DSN al nuevo rol y conserve la contraseña de administrador que estableció antes de iniciar 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 deja sin cifrar la conexión con la base de datos en la red privada de Compose; su puerto nunca se publica en el host. La guía de bases de datos de Zitadel recomienda TLS para las conexiones de producción con la base de datos. Después del primer arranque completo, compruebe que el rol sea realmente el propietario de sus datos:
docker compose exec -T postgres psql -U zitadel -d zitadel -c '\dn'Deberían aparecer un esquema eventstore, un esquema projections y un esquema system. Si faltan esos esquemas, la fase de inicialización no llegó hasta ese punto y el registro del contenedor de API indicará el motivo.
La clave maestra y el coste de perderla
Zitadel cifra los secretos antes de almacenarlos: credenciales del proveedor de identidad, la contraseña SMTP, las semillas de contraseñas de un solo uso y las claves de máquina. La clave maestra desbloquea todos estos datos. Tiene exactamente 32 bytes, y la documentación es clara sobre la consecuencia: no se puede cambiar sin perder el acceso a los datos cifrados.
Genere una y sustituya la línea de marcador de posición en .env:
tr -dc A-Za-z0-9 </dev/urandom | head -c 32; echoEdite la línea ZITADEL_MASTERKEY=MasterkeyNeedsToHave32Characters en lugar de añadir una segunda. Compose utiliza la última definición de una clave repetida, por lo que añadir otra funciona, pero un archivo con dos líneas de clave maestra es una fuente de errores para quien lo lea después.
Ahora piense dónde reside esa clave. El archivo compose inicia el contenedor de API de esta forma:
command: start-from-init --masterkey "${ZITADEL_MASTERKEY}"Por tanto, la clave maestra queda en la línea de comandos del contenedor, donde docker inspect la muestra a cualquiera que pueda acceder al socket de Docker. En un VPS administrado por una sola persona, es un compromiso aceptable, y los permisos de .env son lo que la protege en el disco. Si no es aceptable, monte la clave como un archivo y utilice --masterkeyFile /run/secrets/zitadel-masterkey en su lugar. Así, el valor no aparece entre los argumentos del proceso.
Copie la clave maestra en su gestor de contraseñas antes del primer arranque. No aparece en un volcado de la base de datos, por lo que un volcado restaurado con una clave maestra diferente produce una instancia que no puede leer sus propios secretos. Guárdela en un lugar distinto del archivo que contiene el volcado, para que una copia de seguridad robada no contenga tanto los datos cifrados como la clave que permite descifrarlos.
Establezca el dominio externo antes del primer inicio
ZITADEL_DOMAIN en .env proporciona ZITADEL_EXTERNALDOMAIN al contenedor, y es el nombre que introducen los usuarios. Zitadel deriva de este valor el emisor OIDC, el URI base de la interfaz de inicio de sesión, los endpoints SAML y el nombre de inicio de sesión del primer administrador, por lo que no es un valor meramente estético.
ZITADEL_DOMAIN=auth.example.com
ZITADEL_EXTERNALPORT=443
ZITADEL_EXTERNALSECURE=trueZitadel determina con qué instancia se está comunicando a partir de la cabecera Host. Si esa cabecera no coincide con un dominio que conoce, todas las peticiones reciben la misma respuesta:
ID=QUERY-1kIjX Message=Instance not foundCompruebe dos aspectos cuando vea ese error. Es posible que ZITADEL_DOMAIN no sea el nombre que está utilizando para acceder, o que un proxy situado delante reescriba Host con la dirección del upstream. Acceder a la dirección IP del servidor en lugar de utilizar el nombre también produce este error.
Puede cambiar estos valores más adelante. Zitadel debe volver a ejecutar su fase de configuración para aplicar el cambio, y todas las aplicaciones que ya haya registrado conservarán sus URI de redirección antiguos. Elegir ahora el nombre definitivo resulta mucho más sencillo que cambiarlo después.
Terminar TLS con el overlay de Let's Encrypt
Para un dominio público, añada el overlay de Let's Encrypt de Zitadel. Cambia Traefik al desafío HTTP de ACME (entorno de gestión automática de certificados) y sustituye los puertos publicados por 80 y 443, por lo que ningún otro servicio del sistema puede ocuparlos.
curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/docker-compose.mode-letsencrypt.yml
echo 'LETSENCRYPT_EMAIL=ops@example.com' >> .envEl overlay también establece ZITADEL_EXTERNALPORT: 443 y ZITADEL_EXTERNALSECURE: true en el contenedor de API. Por eso, la URL pública y las URL que Zitadel genera para sí mismo coinciden. El registro A debe resolver antes de iniciar el servicio, porque el desafío HTTP falla sin ese registro.
Si ya termina TLS en nginx o en un balanceador de carga, use docker-compose.mode-external-tls.yml y establezca TRAEFIK_TRUSTED_IPS con los rangos desde los que el proxy envía solicitudes. Traefik sólo acepta las cabeceras X-Forwarded-* procedentes de direcciones incluidas en esa lista. El overlay establece explícitamente en HTTPS la URL externa y las URL de inicio de sesión de Zitadel.
Un proxy ascendente tiene dos funciones que Zitadel exige. Debe usar HTTP/2 para comunicarse con el backend, porque la API usa gRPC. También debe reenviar Host sin cambios junto con X-Forwarded-Proto: https. Con esta pila de Compose, la configuración de nginx tiene esta estructura:
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;
}
}Sustituya los marcadores de posición del upstream por direcciones que nginx pueda alcanzar. Si publica Zitadel en un puerto distinto de 443, use grpc_set_header Host $host:$server_port; para incluir el puerto en la cabecera. El resto es un virtual host normal, y una configuración de proxy inverso de nginx explicada línea por línea cubre las partes que no son específicas de Zitadel.
El primer administrador y cómo forzar el cambio de contraseña
El primer arranque crea una instancia, una organización y un administrador humano. El nombre de inicio de sesión es zitadel-admin@ más zitadel. más el dominio externo, por lo que con ZITADEL_DOMAIN=auth.example.com queda así:
zitadel-admin@zitadel.auth.example.comLa contraseña es Password1!, salvo que defina una propia. El valor predeterminado de upstream de Zitadel obliga a cambiarla en el primer inicio de sesión, pero el archivo compose incluido sustituye ese valor:
ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: falseEsa línea está codificada directamente en docker-compose.yml y no se lee desde .env, por lo que debe colocar sus propios valores en una pequeña sobrecapa independiente. Llámela 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 sólo carga docker-compose.override.yml automáticamente cuando se ejecuta sin la opción -f, y todos los comandos de la guía de Zitadel incluyen -f, lo que desactiva ese comportamiento. En lugar de repetir una lista de opciones cada vez mayor, fije la lista de archivos en .env:
COMPOSE_FILE=docker-compose.yml:docker-compose.mode-letsencrypt.yml:docker-compose.local.ymlAhora inícielo:
docker compose pull
docker compose up -d --wait--wait mantiene el comando en ejecución hasta que las comprobaciones de estado terminan correctamente. Si el contenedor de la API nunca llega a ese estado, Compose se detiene con dependency failed to start: container zitadel-zitadel-api-1 is unhealthy, y docker compose logs zitadel-api contiene el motivo. El contenedor recibe su nombre a partir del proyecto, y el archivo compose incluido lo establece mediante un name: zitadel de nivel superior, por lo que no aparece el nombre del directorio. En el primer arranque, el motivo suele ser la longitud de masterkey o el DSN de la base de datos.
Inicie sesión en https://auth.example.com/ui/console, cambie la contraseña y active después un segundo factor para esa cuenta antes de crear cualquier otro elemento. Cada valor de ZITADEL_FIRSTINSTANCE_* sólo se aplica mientras se crea la primera instancia. Una vez creada la instancia, modificar esos valores no produce ningún efecto.
Por qué el restablecimiento de contraseña no hace nada hasta que SMTP funciona
Un proveedor de identidad que no puede enviar correo falla de una forma que puede pasar desapercibida durante semanas. Zitadel envía correo para las invitaciones de usuarios, la verificación de direcciones, los enlaces de restablecimiento de contraseña, los códigos de un solo uso y los avisos de reclamación de dominios. Si no hay ningún proveedor SMTP configurado, la Console sigue informando de que la acción se ha completado, pero el mensaje pasa al procesamiento de notificaciones sin ningún destino al que enviarlo. En v4.20.0, las notificaciones usan el modo heredado de forma predeterminada (LegacyEnabled: true), que ignora los ajustes MaxAttempts: 3 y MaxTtl: 5m del worker paralelo. Esos valores no describen el comportamiento predeterminado de reintento de las notificaciones. La persona que espera el enlace no recibe ninguna información.
Configúrelo en la Console, en los ajustes de la instancia, en https://auth.example.com/ui/console/settings. El formulario del proveedor SMTP solicita una dirección de correo del remitente, un nombre del remitente, el host y el puerto, un usuario, una contraseña SMTP y un selector de TLS. Use el botón de prueba del formulario antes de guardar, porque envía un mensaje real: llega o no llega. Active el proveedor para que Zitadel lo use para enviar correo.
Existe un conjunto equivalente de variables de entorno, ZITADEL_DEFAULTINSTANCE_SMTPCONFIGURATION_SMTP_HOST y sus variables relacionadas. Se aplican cuando se crea una instancia. En un stack que ya está en ejecución no tienen ningún efecto, por lo que la Console es el lugar adecuado para configurar una instancia existente.
Hay dos aspectos de la entrega desde un VPS que conviene tener en cuenta, porque es donde suele fallar. Compruebe la política de SMTP saliente de su proveedor antes de elegir un relay: DigitalOcean bloquea los puertos 25, 465 y 587 en los Droplets de forma predeterminada, por lo que el puerto 587 no es una solución universal. Use un relay autenticado en un puerto permitido por su proveedor. Publique también registros SPF (sender policy framework) y DKIM (domainkeys identified mail) para el dominio remitente. De lo contrario, el enlace de restablecimiento acabará en el spam, lo que para el usuario parece exactamente que el correo nunca se ha enviado.
En v4.20.0, las conexiones TLS SMTP salientes rechazan las cadenas de certificados que pasan por las CA intermedias comprometidas de eMudhra. Un relay afectado necesita un certificado de reemplazo.
Compruébelo antes de invitar a nadie. Cree un usuario temporal, solicite un restablecimiento de contraseña y monitorice la llegada del mensaje. Si no llega, docker compose logs -f zitadel-api identifica el fallo de SMTP. La contraseña SMTP se almacena cifrada en la base de datos, que es una responsabilidad más que el masterkey gestiona por usted.
Haz copias de seguridad de Postgres y de la masterkey por separado
Toda la información que conoce Zitadel está en PostgreSQL. La masterkey permite descifrarla. Guarda ambas cosas en dos ubicaciones diferentes.
Primero, crea el volcado:
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 es el formato personalizado. Comprime los datos durante la exportación y pg_restore puede leerlos de forma selectiva. exec -T evita que se abra el terminal. Esto es importante porque el comando se ejecuta desde cron sin un terminal asociado.
Después, envía ese directorio a una ubicación externa con restic. restic cifra los datos y elimina los duplicados:
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 se ejecuta una sola vez, sólo el primer día. Añade el volcado y los dos últimos comandos a /usr/local/bin/zitadel-backup.sh y ejecútalo cada noche:
0 3 * * * /usr/local/bin/zitadel-backup.shHaz copias de seguridad de .env y de todos los archivos Compose que uses en git. La masterkey es la excepción. Guárdala en tu gestor de contraseñas y en una segunda ubicación que no sea este repositorio de restic. Un archivo que contiene la base de datos y su clave de descifrado deja de ser una copia de seguridad de un sistema cifrado.
Una copia de seguridad que no has restaurado es sólo una suposición. Restaúrala en una base de datos temporal del mismo servidor y revísala:
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_testUna lista de tablas del esquema eventstore indica que el volcado es válido. Un error que indique que el esquema no existe significa que el volcado no lo es. Habrás descubierto el problema cuando todavía no tiene ningún coste. El patrón general para hacer copias de seguridad y actualizar una pila de Compose se aplica aquí casi sin cambios. Mantener la masterkey fuera del mismo archivo es la única particularidad específica de Zitadel.
Actualice Zitadel sin perder la instancia
Una actualización consiste en cambiar la versión en .env y ejecutar dos comandos:
docker compose pull
docker compose up -d --waitEntienda qué hace el segundo comando antes de ejecutarlo contra una instancia en la que inician sesión usuarios. El comando del contenedor es start-from-init, que ejecuta las fases de init y setup antes de empezar a atender solicitudes, y la fase setup corresponde a las migraciones de la base de datos. Por tanto, un cambio de versión ejecuta migraciones del esquema contra la base de datos activa al iniciar el contenedor, sin intervención, mientras --wait espera a que se complete un healthcheck. Por ese motivo, la prueba de restauración anterior no es opcional.
Realice un volcado nuevo inmediatamente antes de la actualización. El volcado de anoche es diferente.
En v4.20.3, los inicios de sesión en curso mediante proveedores de identidad externos deben reiniciarse, y los códigos de autorización de Login V1 no canjeados se rechazan una vez. Las interfaces de inicio de sesión personalizadas necesitan el permiso session.link para completar solicitudes OIDC o SAML; asigne ese rol a su usuario de servicio mediante IAM_LOGIN_CLIENT antes de actualizar. El usuario de servicio distribuido de Login V2 ya tiene ese rol. Las comprobaciones de contraseñas de Session API aplican ahora la política de inicio de sesión de la organización del usuario, por lo que las organizaciones que deshabiliten el inicio de sesión con nombre de usuario y contraseña deben enviar a los usuarios a su proveedor de identidad.
No salte una versión mayor. Antes de pasar de v3 a v4, actualice primero a v3.4.1 o posterior. v4 hace obligatorias las claves web OIDC y elimina la ruta de firma heredada, por lo que, si su instancia v3 nunca habilitó las claves web, los tokens firmados con las claves heredadas antiguas ya no se podrán verificar después de la actualización. El aviso técnico A-10017 de Zitadel indica que los tokens de acceso JWT y los ID tokens existentes pueden quedar invalidados de inmediato y que los usuarios podrían tener que iniciar sesión otra vez. La solución consiste en pasar primero por v3.4.1 o posterior y dejar que caduquen los tokens y las sesiones firmados con el método heredado antes de actualizar, o aceptar una ventana planificada para que los usuarios vuelvan a iniciar sesión. Si ya ejecuta v3.4.1 o posterior y ha esperado desde que habilitó las claves web, el aviso indica que no es necesario hacer nada.
Supervise la fase setup con docker compose logs -f zitadel-api. Las migraciones de un eventstore grande tardan minutos, y Traefik no dirigirá tráfico a la API hasta que se complete su healthcheck, por lo que el sitio estará caído durante ese intervalo. Planifíquelo en lugar de descubrirlo durante la actualización.
La reversión no consiste en volver a poner la etiqueta anterior. Una vez ejecutadas las migraciones, el binario antiguo no entiende el esquema que encuentra, así que revertir significa restaurar el volcado. Cuando la instancia ya tenga usuarios reales, cambie a docker-compose.prodlike.yml, la superposición que ejecuta init y setup como pasos separados del arranque, para que una migración sea una acción que usted inicia y supervisa, y no un efecto secundario de reiniciar un contenedor.
Qué debe apuntar a su nuevo proveedor de identidad
En la Console, cree un proyecto y después una aplicación dentro de él. Elija OIDC para cualquier aplicación moderna. Zitadel le proporciona un ID de cliente, un secreto de cliente y un documento de descubrimiento en https://auth.example.com/.well-known/openid-configuration. La mayoría del software autoalojado que admite inicio de sesión único necesita exactamente esos datos.
Muchos programas no admiten esta función o sólo la incluyen en un nivel de pago. En el primer caso, oauth2-proxy delante de la aplicación convierte cualquier servicio HTTP en un servicio que Zitadel puede proteger. En el segundo, conviene leer el coste del SSO en las aplicaciones autoalojadas antes de planificar una migración basada en una función por la que todavía no ha pagado.
FAQ
¿Cuánta RAM y CPU necesita un Zitadel autohospedado?
La guía de producción de Zitadel indica que el propio Zitadel necesita aproximadamente 0.5 GB de RAM y puede ejecutarse con menos de un núcleo de CPU. También recomienda mantener 4 núcleos disponibles para el hash de contraseñas. PostgreSQL se calcula por separado, aproximadamente un núcleo por cada 100 solicitudes por segundo y 4 GB de RAM por núcleo. Las cifras mayores de la guía corresponden a cada nodo de un clúster de alta disponibilidad de tres nodos: 4 núcleos y 16 GB por nodo, o aproximadamente 4 núcleos y 8 GB sin recopilación de registros ni métricas. La guía rápida de Compose solicita al menos 2 GB. Esa cantidad basta para probarlo, pero deja poco margen para la base de datos que necesitarán el sistema y otros servicios.
¿Qué ocurre si pierdo la masterkey de Zitadel?
Todo lo que esté cifrado con ella permanece cifrado. Las credenciales de los proveedores de identidad, la contraseña SMTP y las semillas de contraseñas de un solo uso no se pueden descifrar, y la clave no se puede cambiar posteriormente. Un volcado de la base de datos por sí solo no restaura una instancia funcional, porque contiene el texto cifrado, pero no la clave. Guarde la masterkey en un gestor de contraseñas y en un lugar separado de la copia de seguridad que contiene el volcado. Si se pierden ambos, la única opción restante es reconstruir la instancia desde cero.
¿Por qué no llegan nunca los correos de restablecimiento de contraseña de Zitadel?
Porque no hay ningún proveedor SMTP configurado o porque el proveedor configurado no puede entregar los mensajes. Zitadel v4.20.0 usa de forma predeterminada el procesamiento de notificaciones heredado, por lo que se ignoran la configuración de tres intentos y cinco minutos del worker paralelo. Configure el proveedor SMTP en los ajustes de la instancia y use el botón de prueba de ese formulario, que envía un mensaje real. Active el proveedor, use un relay autenticado en un puerto que permita su proveedor de VPS y publique registros SPF y DKIM para el dominio remitente, para que el correo no se filtre como spam.
¿Puedo cambiar el dominio externo de Zitadel después de instalarlo?
Sí, pero no editando sólo .env. Cambie ZITADEL_EXTERNALDOMAIN, ZITADEL_EXTERNALPORT y ZITADEL_EXTERNALSECURE, y deje que Zitadel vuelva a ejecutar su fase de configuración para aplicar el cambio. Las aplicaciones que ya haya registrado conservan sus URI de redirección antiguas y deberá actualizarlas manualmente. Además, cualquier solicitud cuyo encabezado Host no coincida con un dominio que Zitadel conozca recibirá Instance not found. Elegir el nombre definitivo antes del primer arranque evita todos estos problemas.