What ZITADEL asks of the machine
ZITADEL itself is light: its production guide puts the process at about 512 MB of memory and less than one CPU core. The weight sits elsewhere, in the database and in password hashing, which spikes the processor every time somebody signs in with a password.
| Part | What the official docs say |
|---|---|
| ZITADEL process | About 512 MB of memory, under one CPU core |
| The whole Compose stack | At least 2 GB of memory, Docker Engine 24 or later with the Compose plugin |
| Password hashing | CPU spikes at sign-in; the docs suggest 4 cores available for it |
| PostgreSQL | Versions 14 to 18; roughly one core per 100 requests a second and about 4 GB of memory per core |
| Minimal high availability | Three nodes, each with 4 cores and 16 GB of memory |
For an internal login service for a team, a few apps and a few hundred users, the honest summary is: 2 GB of memory is the floor, extra cores help most during busy sign-in minutes, and the database grows with your traffic rather than with your user count.
Why your own virtual machine fits a small identity server
Every other app depends on your identity provider, so keep it somewhere you control. A Cloud VPS in New York gives you root access to your own Linux system, your own IPv4 address and an IPv6 /96, which is everything the Compose stack needs. Traffic it receives is free, and only what it sends counts toward its monthly allowance.
- Docker is a one-click app. Pick Docker when you order and the machine comes up with Docker and Docker Compose installed; you work over SSH. Run
docker versionto confirm the engine is 24 or newer. - A console when SSH will not answer. If a firewall change locks you out, the browser console in your dashboard still reaches the machine.
- Email that ZITADEL can send. Ports 465 and 587 are open from day one, which is what an SMTP provider needs for verification and password-reset mail.
- Room to grow. A machine moves up to any bigger size on request, keeping its files and addresses, after one restart.
The 2 GB size meets the documented floor. The 4 GB size gives PostgreSQL room to cache, and the 8 GB size brings 4 vCPUs, the core count the docs want free for hashing bursts. Our Docker Compose on a VPS guide covers sharing one box between several apps.
Bringing it up on your own domain
Point a DNS record for your login name (for example auth.example.com) at the machine's IPv4 address, and its IPv6 address too if you publish one, before you start: Let's Encrypt checks the name over port 80. Then fetch the official files into a new folder.
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 &&
curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/docker-compose.mode-letsencrypt.yml &&
cp .env.example .env
The example file says plainly that its secrets are insecure defaults for local development. Generate fresh ones with the commands the guide uses, run each line as many times as you need values, and paste the output into .env with an editor:
tr -dc A-Za-z0-9 </dev/urandom | head -c 32; echo
openssl rand -base64 32
- Set
ZITADEL_MASTERKEYto a 32-character value from the first command. It must be exactly 32 characters. - Set
LOGIN_SESSION_COOKIE_SECRETto the output ofopenssl rand -base64 32; it needs at least 32 characters. - Set
POSTGRES_ADMIN_PASSWORDto a new value from the first command (letters and digits only: the / and + that the openssl command can produce would break the DSN), and put the same password intoZITADEL_DATABASE_POSTGRES_DSNin place of the secondpostgresinpostgres:postgres@. The DSN is how ZITADEL logs in to the database, so the two must match or the first start fails. - Set
ZITADEL_DOMAINto your name,ZITADEL_EXTERNALPORT=443,ZITADEL_EXTERNALSECURE=trueandLETSENCRYPT_EMAILto your own address, which registers the Let's Encrypt account (Traefik renews the certificate by itself; Let's Encrypt no longer sends expiry reminders). A mismatch between these and the address people type gives an "Instance not found" error. - Restrict the file to your own user with
chmod 600 .env, because it now holds every secret of the stack. - Start the stack with the Let's Encrypt overlay, then wait for it to report healthy:
docker compose --env-file .env \
-f docker-compose.yml \
-f docker-compose.mode-letsencrypt.yml \
up -d --wait
Other TLS modes exist. External TLS is for a load balancer or CDN that terminates HTTPS in front of the stack, and the local self-signed mode is for a LAN only. Whatever sits in front, ZITADEL uses HTTP/2 for all its connections and the console needs it end to end, so a proxy that downgrades to HTTP/1.1 breaks it.
Close the first-admin window straight away
The first start creates an organization and an admin user called zitadel-admin, whose login name is zitadel-admin@zitadel. followed by your domain. Its documented default password is Password1!, and the Compose file shipped today sets the forced password change on first sign-in to off. From the moment the stack is healthy until you change it, anyone who finds the address can try that password.
The guide also describes ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD for choosing your own starting password, but a value in .env only reaches the container if docker-compose.yml passes it through. Check the file before you rely on it, and change the password in the console either way.
- Sign in at
https://your-domain/ui/consoleas soon as the stack reports healthy, and change the admin password. - Add a second factor to that account, then open the default settings page and decide whether to force MFA for everyone.
- Under Login Behavior and Security, turn off Register allowed unless strangers really should be able to create accounts on your login page.
- Set Maximum Password Attempts in the lockout settings so a guessed password locks the account; 0 switches lockout off.
- Add your own SMTP provider and activate it. The built-in one is for testing only, and only one provider can be active.
Keeping it healthy: backups, the masterkey and upgrades
ZITADEL keeps no state of its own: it is event sourced, and it can rebuild everything from the eventstore.events2 table in PostgreSQL. Back up the database and you have backed up the service. PostgreSQL's own pg_dump makes a consistent copy while the database is in use, and its custom format (-Fc) is compressed and restores with pg_restore. Run it inside the postgres container on a schedule and copy the file off the machine.
A database copy without the masterkey is not a working backup. The masterkey encrypts sensitive data at rest and cannot be changed after the first start without losing access to that data. Store the .env file, or at least the key, in a password manager or a second location that is not this server, and test a restore on a spare machine rather than over the live database.
Upgrades are a version bump: change ZITADEL_VERSION in .env, then pull and start again. The guide's upgrade commands name only docker-compose.yml; in Let's Encrypt mode add the overlay to both, exactly as in the start command, or the stack comes back on the plain HTTP settings. Take a fresh database dump first. ZITADEL_FIRSTINSTANCE_ and ZITADEL_DEFAULTINSTANCE_ settings only apply on the very first start; later changes go through the console.
For security, the production guide strongly advises rate limiting and bot detection in front of the login. Keep PostgreSQL unpublished, as the Compose file leaves it. If you add a host firewall, allow SSH first and remember Docker's own documentation: its published ports bypass ufw rules, so the ports the overlay publishes stay reachable whatever ufw says.
When a VPS is the wrong home for it
A Cloud VPS shares its physical server with other customers, and processor time is shared rather than reserved. That is fine for a team's single sign-on; it is the wrong fit when sign-in volume is high enough that hashing bursts need cores nobody else touches. It also runs in New York only, so users on another continent pay the round trip on every redirect.
The documented minimal high-availability shape is three nodes of 4 cores and 16 GB each, and for Kubernetes the project points to its official Helm chart. For that, look at whole dedicated servers, where every core is yours and the port is unmetered, or Kubernetes on bare metal you run yourself.
Questions people ask
- Can I use an existing PostgreSQL server instead of the bundled one?
- Yes. ZITADEL supports PostgreSQL 14 to 18, and it connects with whatever
ZITADEL_DATABASE_POSTGRES_DSNsays. When a DSN is set, ZITADEL uses that user directly and does not create a separate one, so the user must exist already. For production the example file recommends a role without superuser rights. - What happens if I lose the masterkey?
- You lose access to the data ZITADEL encrypted with it, and the key cannot be swapped for a new one after initialization. The database alone will not bring those secrets back. Keep a copy of the key somewhere other than the server from the day you generate it.
- Why does my browser show "Instance not found"?
- The domain, port or HTTPS setting in
.envdoes not match the address you typed.ZITADEL_DOMAIN,ZITADEL_EXTERNALPORTandZITADEL_EXTERNALSECUREmust describe the public address exactly: your name, 443 and true for any TLS mode. Fix the values and start the stack again. - Which machine size should I start on?
- The Compose stack's documented minimum is 2 GB of memory, so start there for a test or a small team. Move up when sign-ins feel slow or PostgreSQL needs more cache: a VPS can be moved to any bigger size later, keeping its files and addresses. For high availability, plan on three machines instead of one larger one.