Workload · Running your own ZITADEL login

ZITADEL Self Hosted on a Server You Run: Setup, Secrets and Sign-In

Running ZITADEL self hosted means one Linux machine with Docker Compose, a PostgreSQL database, a 32-character masterkey you generate before the first start, and a domain name for HTTPS. The official Compose stack bundles all of it: a Traefik proxy in front, the ZITADEL API, the new login screen and PostgreSQL behind them. Below: what that stack asks of a server, how to bring it up on your own domain without leaving the default admin password open, and what to back up.

The short version
  1. The Compose stack wants at least 2 GB of memory and Docker Engine 24 or later
  2. The masterkey cannot be changed after the first start, so keep a copy off the server
  3. Let's Encrypt mode publishes only ports 80 and 443; PostgreSQL stays inside Docker
  4. The first admin starts on a documented default password: change it in the first minute

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.

PartWhat the official docs say
ZITADEL processAbout 512 MB of memory, under one CPU core
The whole Compose stackAt least 2 GB of memory, Docker Engine 24 or later with the Compose plugin
Password hashingCPU spikes at sign-in; the docs suggest 4 cores available for it
PostgreSQLVersions 14 to 18; roughly one core per 100 requests a second and about 4 GB of memory per core
Minimal high availabilityThree 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 version to 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
  1. Set ZITADEL_MASTERKEY to a 32-character value from the first command. It must be exactly 32 characters.
  2. Set LOGIN_SESSION_COOKIE_SECRET to the output of openssl rand -base64 32; it needs at least 32 characters.
  3. Set POSTGRES_ADMIN_PASSWORD to 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 into ZITADEL_DATABASE_POSTGRES_DSN in place of the second postgres in postgres:postgres@. The DSN is how ZITADEL logs in to the database, so the two must match or the first start fails.
  4. Set ZITADEL_DOMAIN to your name, ZITADEL_EXTERNALPORT=443, ZITADEL_EXTERNALSECURE=true and LETSENCRYPT_EMAIL to 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.
  5. Restrict the file to your own user with chmod 600 .env, because it now holds every secret of the stack.
  6. 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.

  1. Sign in at https://your-domain/ui/console as soon as the stack reports healthy, and change the admin password.
  2. Add a second factor to that account, then open the default settings page and decide whether to force MFA for everyone.
  3. Under Login Behavior and Security, turn off Register allowed unless strangers really should be able to create accounts on your login page.
  4. Set Maximum Password Attempts in the lockout settings so a guessed password locks the account; 0 switches lockout off.
  5. 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_DSN says. 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 .env does not match the address you typed. ZITADEL_DOMAIN, ZITADEL_EXTERNALPORT and ZITADEL_EXTERNALSECURE must 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.

Run your own login service

Order a Cloud VPS with Docker ready, point your domain at it and have ZITADEL answering on HTTPS the same evening.

Get a server for ZITADEL

Read next