SSD Nodes Learn Hosting plans →
Guides Matt ConnorBy Matt Connor

Self-host Zitadel on a VPS with Docker

Zitadel itself needs about 512MB of RAM. Set up Postgres, the masterkey, TLS, SMTP and backups on one VPS, and learn what an upgrade does to your database.

What you need to self-host Zitadel on a VPS

To self-host Zitadel on a VPS you need a Docker host, a public DNS name pointing at it, PostgreSQL, and enough CPU and RAM for both. Zitadel's production guide puts the application itself at about 512 MB of RAM and under one CPU core. The database and password hashing are what grow. Zitadel is an identity provider. It issues tokens over OIDC (OpenID Connect) and SAML (security assertion markup language) so your other services stop keeping their own user lists. The install is a curl and a docker compose up. The parts that decide whether it survives are the masterkey, the database user, SMTP (simple mail transfer protocol), the backup, and the first upgrade.

Everything below assumes Ubuntu 24.04, Docker Engine 24 or newer with the Compose plugin version 2.24.4 or newer, and a name like auth.example.com already resolving to the server. The TLS overlays use !override, which requires that Compose version.

How much VPS does Zitadel need?

The Compose quickstart in Zitadel's docs asks for 2 GB of RAM. That number is for the quickstart. Zitadel's production guide publishes different figures.

ChartZitadel's own published sizing guidance, October 2026
The data behind this chart
[
  {
    "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
  }
]

Those are published recommendations, not measurements from a running box. Read them as the shape of the problem. The Zitadel process itself is small: the guide puts it at about 0.5 GB of RAM and says it can run on less than one CPU core. The cores are for password hashing, which is deliberately slow, so a burst of logins arrives as a CPU spike, and the guide recommends keeping 4 CPU cores available for it. PostgreSQL is the other half of the bill: the same guide budgets about one core per 100 requests per second and 4 GB of RAM per core.

The two larger rows are not single-box numbers. For a minimal high-availability setup the guide recommends a cluster of three nodes, each with 4 cores and 16 GB, and says you can reduce that to about 4 cores and 8 GB per node if you leave out log collection and metrics. It names no sizing for a single node.

So a 2 GB VPS will start this stack, and it is well below what the guide budgets for the database alone once real traffic arrives. Login is the service every other service depends on. When it is down, nothing that trusts it lets anyone in. Deciding that the guide's database and hashing budget is more than you want to spend on authentication is a reasonable call, and it is far cheaper to make now than after a migration. The comparison of Keycloak, Authentik and Zitadel covers what each one costs in memory and in operational work, and a self-hosted Authentik server is the usual answer on a smaller box.

Get the stack and pin a 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

That file defines four services you will actually run. Traefik is the reverse proxy: it routes by path and, with the overlay further down, terminates TLS (transport layer security). zitadel-api is the Go binary on port 8080. zitadel-login is the login interface served at /ui/v2/login. postgres holds everything. A Redis cache and an OpenTelemetry collector sit in the same file behind Compose profiles and stay off until you ask for them.

Do not run docker compose up yet. The first start creates the instance, and several settings below cannot be changed afterwards without extra work.

The .env you copied pins its own image tags:

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

The current v4 release is v4.20.3, released on 13 November 2026, four minor versions ahead of the pin in the shipped file. The release before v4.20.0, v4.19.5 from 15 October 2026, is the first one covered by Zitadel's technical advisory A-10018: affected list endpoints in the v1 and v2 APIs now apply default and maximum limits, so a client that lists without a limit no longer gets every result and has to paginate, and a request that asks for more than the maximum is rejected. Every later release, v4.20.0 included, carries that change. Set ZITADEL_VERSION to the version you mean to run, and stay on the v4 line rather than tracking whatever is newest. Skip v4.18.0 if you pick a version by hand: its release notes say the setup step fails in that version and to use v4.19.0 instead. The curl above pulls docker-compose.yml from the main branch, which is pinned to nothing, so commit your copy of both files to a git repository. Otherwise the same command on a new box next month gives you a different file and you will not know what changed.

Replace LOGIN_SESSION_COOKIE_SECRET in .env with a random value generated by openssl rand -base64 32. The Login UI uses it to sign session cookies, and the v4.19.5 release notes explicitly warn against keeping the example value.

Give Postgres its own user and a real password

The shipped .env connects Zitadel to PostgreSQL as the superuser, with the password postgres:

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

There is a trap in the hardening step here. Zitadel's docs tell you to append POSTGRES_ZITADEL_PASSWORD to .env, but the base docker-compose.yml never reads that variable, so setting it changes nothing. Changing POSTGRES_ADMIN_PASSWORD on its own breaks the connection instead, because the password is also written literally inside the DSN (data source name) string. The DSN is the line that decides how Zitadel connects.

The comments in .env.example say the rest plainly: when a DSN is configured, Zitadel uses that user directly and does not create an unprivileged one for you, so the role has to exist before the first start. Generate a password for the role, set POSTGRES_ADMIN_PASSWORD to a separate random password in .env before starting Postgres, then start Postgres on its own and create the role. The Postgres image only applies that admin password when it initializes an empty data directory; changing .env later does not rotate an existing database password.

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

Those psql calls run inside the container over its local socket, which the official Postgres image trusts, so they do not prompt for a password. Ownership is the part that matters. Zitadel's init phase creates its own schemas (eventstore, projections, system) and tables. Database ownership gives the role the CREATE privilege needed to bootstrap those schemas. PostgreSQL 15's change to CREATE permissions on the public schema is separate and does not imply that Zitadel's schema bootstrap fails.

Now point the DSN at the new role, and keep the admin password you set before starting 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 leaves the database connection unencrypted on the private Compose network; its port is never published to the host. Zitadel's database guide recommends TLS for production database connections. After the first full start, check that the role really owns its data:

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

That should list an eventstore schema, a projections schema and a system schema. If those schemas are missing, the init phase never got that far, and the API container log will say why.

The masterkey, and what losing it costs

Zitadel encrypts secrets before it stores them: identity provider credentials, the SMTP password, one-time-password seeds and machine keys. The masterkey unlocks all of it. It is exactly 32 bytes, and the docs are blunt about the consequence: it cannot be changed without losing access to encrypted data.

Generate one and replace the placeholder line in .env:

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

Edit the ZITADEL_MASTERKEY=MasterkeyNeedsToHave32Characters line rather than appending a second one. Compose takes the last definition of a repeated key, so appending does work, but a file holding two masterkey lines is a trap for whoever reads it next.

Now think about where that key lives. The compose file starts the API container like this:

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

The masterkey therefore sits on the container command line, where docker inspect shows it to anyone who can reach the Docker socket. On a single-admin VPS that is an acceptable trade, and the mode on .env is what protects it on disk. If it is not acceptable, mount the key as a file and use --masterkeyFile /run/secrets/zitadel-masterkey instead, which keeps the value out of process arguments.

Copy the masterkey into your password manager before the first start. It does not appear in a database dump, so a dump restored under a different masterkey produces an instance that cannot read its own secrets. Keep it somewhere other than the archive that holds the dump, so one stolen backup does not contain both the encrypted data and the key to it.

Set the external domain before the first start

ZITADEL_DOMAIN in .env feeds ZITADEL_EXTERNALDOMAIN in the container, and it is the name your users type. Zitadel derives the OIDC issuer, the login interface base URI, the SAML endpoints and the first admin's login name from it, so it is not cosmetic.

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

Zitadel resolves which instance you are talking to from the Host header. If that header does not match a domain it knows, every request gets the same answer:

ID=QUERY-1kIjX Message=Instance not found

Check two things when you see that error. Either ZITADEL_DOMAIN is not the name you are browsing to, or a proxy in front is rewriting Host to the upstream address. Browsing to the server's IP address instead of the name produces it as well.

You can change these values later. Zitadel has to rerun its setup phase to pick the change up, and every application you already registered keeps its old redirect URIs. Choosing the final name now is much cheaper than moving it.

Terminate TLS with the Let's Encrypt overlay

For a public domain, add Zitadel's Let's Encrypt overlay. It switches Traefik to the ACME (automatic certificate management environment) HTTP challenge and replaces the published ports with 80 and 443, so nothing else on the box may hold either one.

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

The overlay also sets ZITADEL_EXTERNALPORT: 443 and ZITADEL_EXTERNALSECURE: true on the API container, which is why the public URL and the URLs Zitadel builds for itself agree. The A record has to resolve before you start, because the HTTP challenge fails without it.

If you already terminate TLS on nginx or on a load balancer, use docker-compose.mode-external-tls.yml instead and set TRAEFIK_TRUSTED_IPS to the ranges your proxy sends from. Traefik only honours X-Forwarded-* headers from addresses in that list. The overlay explicitly sets Zitadel's external URL and login URLs to HTTPS.

An upstream proxy has two jobs Zitadel is strict about. It must speak HTTP/2 to the backend, because the API is gRPC. And it must pass Host through unchanged along with X-Forwarded-Proto: https. With this Compose stack, the nginx configuration has this shape:

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

Replace the upstream placeholders with addresses nginx can reach. If you serve Zitadel on a port other than 443, use grpc_set_header Host $host:$server_port; so the port travels with the header. The rest is an ordinary virtual host, and an nginx reverse proxy config read line by line covers the parts that are not Zitadel-specific.

The first admin, and forcing the password change

The first start creates one instance, one organisation and one human admin. The login name is zitadel-admin@ plus zitadel. plus your external domain, so with ZITADEL_DOMAIN=auth.example.com it is:

zitadel-admin@zitadel.auth.example.com

The password is Password1! unless you set your own. Zitadel's upstream default is to force a change at first login, and the shipped compose file overrides that default:

ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: false

That line is hardcoded in docker-compose.yml rather than read from .env, so put your own values in a small overlay of your own. Call it 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 only loads docker-compose.override.yml on its own when you run it with no -f flag, and every command in Zitadel's guide passes -f, which turns that off. Rather than repeating a growing list of flags, pin the file list in .env:

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

Now start it:

docker compose pull
docker compose up -d --wait

--wait holds the command until the healthchecks pass. When the API container never gets there, Compose stops with dependency failed to start: container zitadel-zitadel-api-1 is unhealthy, and docker compose logs zitadel-api has the reason. The container is named after the project, and the shipped compose file sets that itself with a top-level name: zitadel, so the directory name does not appear. On a first start the reason is usually the masterkey length or the database DSN.

Log in at https://auth.example.com/ui/console, change the password, then turn on a second factor for that account before you create anything else. Every ZITADEL_FIRSTINSTANCE_* value applies only while the first instance is being created. Once the instance exists, editing them does nothing at all.

Why password reset does nothing until SMTP works

An identity provider that cannot send mail is broken in a way that stays hidden for weeks. Zitadel sends email for user invitations, address verification, password reset links, one-time codes and domain claim notices. With no SMTP provider configured, the Console still reports the action as done, and the message goes to notification processing with nowhere to send it. In v4.20.0, notifications use legacy mode by default (LegacyEnabled: true), which ignores the parallel worker's MaxAttempts: 3 and MaxTtl: 5m settings. Those values do not describe the default notification retry behaviour. Nothing tells the person waiting for the link.

Configure it in the Console, under instance settings at https://auth.example.com/ui/console/settings. The SMTP provider form asks for a sender email address, a sender name, the host and port, a user, an SMTP password and a TLS toggle. Use the test button in that form before you save, because it sends a real message: it either arrives or it does not. Activate the provider so Zitadel uses it to send mail.

There is a matching set of environment variables, ZITADEL_DEFAULTINSTANCE_SMTPCONFIGURATION_SMTP_HOST and its siblings. They apply when an instance is created. On a stack that is already running they have no effect, so the Console is the right place for an existing instance.

Two things about delivery from a VPS, because this is where it usually fails. Check your provider's outbound SMTP policy before choosing a relay: DigitalOcean blocks ports 25, 465 and 587 on Droplets by default, so port 587 is not a universal workaround. Use an authenticated relay on a port your provider permits. And publish SPF (sender policy framework) and DKIM (domainkeys identified mail) records for the sending domain, or the reset link lands in spam, which looks to the user exactly like the mail never being sent.

On v4.20.0, outbound SMTP TLS connections reject certificate chains through the compromised eMudhra intermediate CAs. An affected relay needs a replacement certificate.

Prove it before you invite anyone. Create a throwaway user, ask for a password reset, and watch the message arrive. If it does not, docker compose logs -f zitadel-api names the SMTP failure. The SMTP password is stored encrypted in the database, which is one more thing the masterkey is holding for you.

Back up Postgres and the masterkey separately

Everything Zitadel knows is in PostgreSQL. The thing that decrypts it is the masterkey. Back them up to two different places.

The dump first:

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 is the custom format, which compresses on the way out and which pg_restore can read selectively. exec -T drops the terminal, which matters because this runs from cron with no terminal attached.

Then push that directory offsite with restic, which encrypts and deduplicates:

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 runs once, on the first day only. Put the dump and the last two commands in /usr/local/bin/zitadel-backup.sh and run it nightly:

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

Back up .env and every compose file you use, in git. The masterkey is the exception to all of this. It belongs in your password manager and in a second location that is not this restic repository, because an archive holding the database and its decryption key together stops being a backup of an encrypted system.

A backup you have not restored is a guess. Restore into a scratch database on the same server and look at it:

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

A list of tables in the eventstore schema means the dump is real. An error saying the schema does not exist means it is not, and you have found that out on a day when it costs you nothing. The general pattern for backing up and upgrading a Compose stack applies here almost unchanged, and keeping the masterkey out of the same archive is the only Zitadel-specific part.

Upgrading Zitadel without losing the instance

An upgrade is a version bump in .env followed by two commands:

docker compose pull
docker compose up -d --wait

Understand what the second one does before you run it against something people log in to. The container's command is start-from-init, which runs the init and setup phases before it starts serving, and the setup phase is the database migrations. So a version bump runs schema migrations against your live database at container start, unattended, while --wait sits there waiting on a healthcheck. That is the whole reason the restore test above is not optional.

Take a fresh dump immediately before the upgrade. Last night's dump is a different thing.

For v4.20.3, external identity provider sign-ins in progress must restart, and unredeemed Login V1 authorization codes are rejected once. Custom login UIs need session.link permission to complete OIDC or SAML requests; grant their service user IAM_LOGIN_CLIENT before upgrading. The shipped Login V2 service user already has that role. Session API password checks now enforce the user's organisation login policy, so organisations that disable username/password login must send users to their identity provider.

Do not jump a major version. Before moving from v3 to v4, get onto v3.4.1 or later first. v4 makes OIDC web keys mandatory and removes the legacy signing path, so if your v3 instance never enabled web keys, tokens signed with the old legacy keys are no longer verifiable after the upgrade. Zitadel's technical advisory A-10017 says existing JWT access tokens and ID tokens may become invalid immediately and users may have to sign in again. Its fix is to stage through v3.4.1 or later and let legacy-signed tokens and sessions expire before you upgrade, or to accept a planned re-login window. If you already run v3.4.1 or later and have waited since web keys were enabled, the advisory says no action is needed.

Watch the setup phase with docker compose logs -f zitadel-api. Migrations on a large eventstore take minutes, and Traefik will not route to the API until its healthcheck passes, so the site is down for that window. Plan it rather than discovering it.

Rollback is not a matter of putting the old tag back. Once the migrations have run, the older binary does not understand the schema it finds, so rolling back means restoring the dump. Once the instance carries real users, move to docker-compose.prodlike.yml, the overlay that runs init and setup as steps separate from start, so a migration is something you trigger and watch instead of a side effect of a container restart.

What to point at your new identity provider

In the Console, create a project and then an application inside it. Pick OIDC for anything modern, and Zitadel gives you a client ID, a client secret and a discovery document at https://auth.example.com/.well-known/openid-configuration. Most self-hosted software that supports single sign-on wants exactly those.

Plenty of software does not support it, or supports it only in a paid tier. For the first case, oauth2-proxy in front of the app turns any HTTP service into something Zitadel can guard. For the second, the SSO tax in self-hosted apps is worth reading before you plan a migration around a feature you have not paid for.

FAQ

How much RAM and CPU does a self-hosted Zitadel need?

Zitadel's production guide says Zitadel itself needs about 0.5 GB of RAM and can run on less than one CPU core, and it recommends keeping 4 cores available for password hashing. PostgreSQL is budgeted separately, at roughly one core per 100 requests per second and 4 GB of RAM per core. The larger figures in the guide are per node in a three-node high-availability cluster: 4 cores and 16 GB each, or about 4 cores and 8 GB without log collection and metrics. The Compose quickstart asks for at least 2 GB, which is enough to try it and leaves little room for the database a system other services depend on will need.

What happens if I lose the Zitadel masterkey?

Everything encrypted with it stays encrypted. Identity provider credentials, the SMTP password and one-time-password seeds cannot be decrypted, and the key cannot be changed after the fact. A database dump on its own does not restore a working instance, because the dump holds ciphertext and no key. Store the masterkey in a password manager, in a place separate from the backup that holds the dump. If both are gone, rebuilding the instance from scratch is the only path left.

Why do Zitadel password reset emails never arrive?

Because no SMTP provider is configured, or the configured one cannot deliver. Zitadel v4.20.0 uses legacy notification processing by default, so the parallel worker's three-attempt and five-minute settings are ignored. Configure the SMTP provider under instance settings and use the test button in that form, which sends a real message. Activate the provider, use an authenticated relay on a port your VPS provider permits, and publish SPF and DKIM records for the sending domain so the mail is not filtered as spam.

Can I change the Zitadel external domain after installing?

Yes, but not by editing .env alone. Change ZITADEL_EXTERNALDOMAIN, ZITADEL_EXTERNALPORT and ZITADEL_EXTERNALSECURE, then let Zitadel rerun its setup phase so it picks the change up. Applications you already registered keep their old redirect URIs and have to be updated by hand, and any request whose Host header does not match a domain Zitadel knows gets Instance not found back. Choosing the final name before the first start avoids all of it.

Was this article useful?