Published

Keycloak

Identity and access management server: single sign-on over OpenID Connect, OAuth 2.0 and SAML for your apps, with realms, user federation (LDAP, Kerberos), social and enterprise login, two-factor authentication and an admin console. The self-hosted stack is one Java (Quarkus) server and PostgreSQL, which holds all of its state.

Resources by load level

What the app itself needs at each level, next to what we recommend for a server that runs only this app.

Level	What it means	App requirements	Recommended
LightEstimate	Up to 1,000 users in a few realms and ~10 client apps; peaks of 2 password logins and 24 token refreshes a second.	2 vCPU · 3 GiB RAM · 7.5 GiB disk	2.52 vCPU · 5.1 GiB RAM · 18.055 GiB disk
MediumEstimate	Up to 10,000 users; peaks of 6 password logins, 48 token refreshes and 12 client credential grants a second.	3.25 vCPU · 3 GiB RAM · 7.5 GiB disk	4.02 vCPU · 5.1 GiB RAM · 18.055 GiB disk
HeavyEstimate	Up to 50,000 users; peaks of 12 password logins, 96 token refreshes and 24 client credential grants a second.	6.5 vCPU · 6 GiB RAM · 52.5 GiB disk	7.92 vCPU · 8.7 GiB RAM · 69.805 GiB disk

Recommended = app requirements + system baseline + safety headroom, under sizing policy 2026.10.0. Options stay at their defaults. “Estimate” means the sources give no number for that case, so it is worked out from them by the method stated under Components. How the numbers are built

Size it in the Stack Sizer

Ready-to-run files

Support level Supported

Compose template from the official sources; not yet verified by a run.

Create docker-compose

Components

What each component needs at each load level, before baseline and headroom.

vCPU / GiB RAM / GiB disk
Component	Light	Medium	Heavy	Sources
Keycloak server (app)	1 / 2 / 1	2.25 / 2 / 1	4.5 / 2 / 1	[2][13][14][15][31]
PostgreSQL (database)	1 / 1 / 6.5	1 / 1 / 6.5	2 / 4 / 51.5	[7][8][14][15][35][36][37][38][39][40][41]

How the estimates are worked out

Keycloak server · Light: CPU by the sizing guide: 2 logins/s ÷ 15 + 24 refreshes/s ÷ 120 = 0.333 vCPU, plus 150% headroom = 0.833, rounded up to 1 vCPU. RAM: the container guide's 2 GB for small production (base use 1250 MB with caches and 10,000 sessions); heap pinned at 1434 MiB. Disk: 265,677,312 B compressed image × 3 = 0.742 GiB, rounded up to 1 GiB; no data on disk.
Keycloak server · Medium: CPU by the sizing guide: 6 ÷ 15 + 48 ÷ 120 + 12 ÷ 120 = 0.9 vCPU (refreshes at the guide's 1:8 login ratio), plus 150% headroom = 2.25 vCPU. RAM stays at 2 GiB: memory follows the cached data (10,000 entries per cache by default), not the request rate. Disk: 0.742 GiB image, rounded up to 1 GiB.
Keycloak server · Heavy: CPU by the sizing guide: 12 ÷ 15 + 96 ÷ 120 + 24 ÷ 120 = 1.8 vCPU, plus 150% headroom = 4.5 vCPU; password hashing takes most of it. RAM stays at 2 GiB: the guide's own example serves 45 logins/s per cluster with 1250 MB per node. Disk: 0.742 GiB image, rounded up to 1 GiB.
PostgreSQL · Light: ~26 login, logout and refresh requests/s × 0.35–0.7 vCPU per 100 (Keycloak's database measurements) = 0.09–0.18 vCPU over a 0.3 vCPU idle load, inside the sidecar's 1 vCPU; ~364 write IOPS. The pool is capped at 20 connections. Light preset method: shared_buffers 25% of RAM, 0.5 GiB image + 5 GiB data + 1 GiB WAL.
PostgreSQL · Medium: ~55 login, logout and refresh requests/s × 0.35–0.7 vCPU per 100 = 0.19–0.39 vCPU over a 0.3 vCPU idle load, still inside 1 vCPU; ~770 write IOPS. 10,000 users × an assumed 20 KB of rows = 0.2 GB, inside 5 GB; pool capped at 20. Light preset method: shared_buffers 25% of RAM, 0.5 GiB image + 5 GiB data + 1 GiB WAL.
PostgreSQL · Heavy: ~110 login, logout and refresh requests/s × 0.35–0.7 vCPU per 100 = 0.38–0.77 vCPU over a 0.3 vCPU idle load: up to 1.07 vCPU, past the sidecar's 1 vCPU, so the PostgreSQL profile's medium preset (2 vCPU, 4 GiB). ~1,540 write IOPS. 50,000 users × an assumed 20 KB = 1 GB of rows.

Ports

Public ports are meant to be reached from outside the stack, usually through a reverse proxy; internal ones stay on the stack's own network.

Component	Port	Exposure	Purpose	Sources
Keycloak server	8080/tcp	Public, through a proxy	Login pages, OIDC/SAML endpoints, Admin Console and Admin API (HTTP; TLS at the proxy)	[5][11]
Keycloak server	9000/tcp	Internal only	Management interface: /health and /metrics; never expose it	[3][4]
Keycloak server	7800/tcp	Internal only	JGroups unicast transport of the ispn caches (jdbc-ping stack)	[10]
Keycloak server	57800/tcp	Internal only	JGroups failure detection (FD_SOCK2, bind port + 50000)	[10]
PostgreSQL	5432/tcp	Internal only	PostgreSQL connections from Keycloak (also its jdbc-ping node registry)	[7][40]

Every port in the catalog, with conflicts between apps

User and permissions (UID/GID)

The user each container's process runs as, and the paths it writes to. A bind mount for one of these paths must be writable by that UID:GID.

Component	UID:GID	User	Starts as root	Writes to	Sources
Keycloak serverDerived	1000:0	`keycloak`	No	`/opt/keycloak/data/opt/keycloak/lib`	[11][16][17]
PostgreSQL	999:999	`postgres`	Yes, prepares its directories, then drops to this user	`/var/lib/postgresql/var/run/postgresql`	[33][34][40]

Keycloak server: USER 1000 (keycloak, group 0) from the start, with /opt/keycloak owned by 1000:0 and group-writable. data/ holds runtime files; start without --optimized writes its build into lib/. Neither needs a volume: realms, users and sessions live in PostgreSQL.

Storage growth

How much each component's data grows per month at each load level, on top of the disk in the profile. A value marked Assumption is ANAROQ's stated assumption, not a figure from the sources; the notes say what it rests on.

GiB per month
Component	Light	Medium	Heavy	Sources
PostgreSQLAssumption	0.001	0.01	0.05	[19][27]

What the growth figures rest on

PostgreSQL: New users a month (an assumed 50, 500 and 2,500) × an assumed 20 KB of rows each. Sessions are persisted but expire, so they hold a steady size; stored user and admin events are off by default and, once on, grow until their expiration removes them.

Upgrade and rollback

How to move to a new version safely, and how to go back if it fails.

Back up first

Take a pg_dump of the keycloak database and keep the .env: the migrated schema no longer works with the old server. [22]

Upgrade steps

Read the upgrade notes of every version between yours and the new one in the Upgrading Guide: breaking changes are listed per release. [21]
Change the pinned keycloak tag, then run docker compose pull and docker compose up -d. Compose stops the old container first, as minor and major upgrades require; the schema migrates at the first start (30 minute timeout). Follow docker compose logs -f keycloak until it is healthy. [22][23]
On tables over 300,000 rows the migration skips new indexes and PostgreSQL builds them in the background after startup; expect extra database load for a while. [23]

Roll back

Keycloak cannot roll back database changes: stop it, restore the dump from before the upgrade, and pin the image back to the previous tag. [21][22]

Known breaking changes

In 26.8.1: With Enable StartTLS on, SMTP now requires a successful STARTTLS upgrade instead of falling back to plaintext; email fails against servers without STARTTLS. [24]
In 26.8.0: Login failures for brute force detection are stored in the database by default, with more database connections and CPU; disabled clients no longer appear in token audiences. [25]
In 26.7.0: The view-system admin role was removed, the shutdown timeout grew from 1 s to 10 s, and ephemeral writes (sessions, events) use PostgreSQL async commit. [26]
In 26.0.0: KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD gave way to KC_BOOTSTRAP_ADMIN_USERNAME and KC_BOOTSTRAP_ADMIN_PASSWORD; hostname v1 and the proxy option were removed, and all user sessions are persisted in the database. [27]

Limits

One Keycloak node. CPU follows password hashing: 1 vCPU per 15 password logins a second, plus 150% headroom. The heap is pinned at 1434 MiB for the 2 GiB preset; change JAVA_OPTS_KC_HEAP if you give Keycloak more memory. [2][13][14]
Sessions live in PostgreSQL: every 100 login, logout and refresh requests a second need about 1,400 write IOPS, so a slow disk limits throughput before CPU does. [7][15]
The stock image runs its build at every start, which makes starts slower. Custom providers, themes or build options such as features need an optimized image of your own, which the template does not build. [2][16]

Security

The admin from .env is temporary and exists only to get in: sign in, create a permanent admin with two-factor authentication, then delete the temporary account. The bootstrap variables are ignored once the master realm exists. [16][18]
The proxy forwards everything. The reverse proxy guide recommends exposing only /realms/, /resources/ and /.well-known/, and keeping /admin/ and /realms/master/ internal: block them at your proxy, or use the master realm only from a private network. [5][6]
Behind a proxy Keycloak trusts X-Forwarded-* headers (KC_PROXY_HEADERS=xforwarded). Your proxy must set and overwrite them, and port 8080 must not be reachable around it; health and metrics stay on the unpublished port 9000. [4][5]
Brute force detection is off by default. Turn it on in each realm (Realm settings, Security defenses) before exposing login pages. [19]

Backup

All state is in PostgreSQL: realms, users, credentials, clients, signing keys and sessions. Back up a pg_dump of the keycloak database together with the .env; the Keycloak container has no volume. [7][22]
Realm exports from the Admin Console are not backups: they leave out secrets and users. Only exports taken at boot (kc.sh export) are fit for backups or moving to another server. [19][20]