The self-hosted Keycloak distribution
Production-ready, on your own machines: HA cluster, PostgreSQL with automatic failover, encrypted backups with point-in-time recovery, monitoring, and — the part nobody ships — an upgrade path that is re-proven in public CI every night. Apache-2.0.
Keycloak is powerful. Running it in production is not.
Keycloak has no rolling upgrades across minor versions, a cluster layer that is easy to misconfigure, and a realm import/export story that loses settings. Managed vendors solve this by hosting your identity data on their cloud. If you can't or won't do that — regulated industry, data residency, air-gapped — you are on your own. keelinfra is the third option: a distribution you run yourself, with the ops knowledge open instead of paywalled.
No containers required. No operator. No Kubernetes.
Three clean VMs and SSH. Ansible runs from your control node; nothing is pre-installed on the targets. Every component below is in the open source distribution — there is no gated tier.
| Component | What it does |
|---|---|
| Keycloak | Official upstream release, systemd-managed, DB-persisted sessions, jdbc-ping clustering — a node can die without logging anyone out |
| PostgreSQL + Patroni + etcd | Automatic leader failover; writes keep flowing when the database leader goes down |
| HAProxy (+ optional keepalived VIP) | Load balancing and TLS on every node; drain-aware rolling upgrades |
| pgBackRest | Encrypted, scheduled backups with point-in-time recovery — restore-tested by drill |
| Prometheus + Grafana | Dashboards and alert rules for the things that actually page you |
| keycloak-config-cli | Realms, clients and roles as declarative config — git is the source of truth |
~10 minutes on 3 clean VMs
$ git clone https://github.com/keelinfra/keycloak && cd keycloak $ ./configure -c examples/ha-3node.yml # describe your nodes $ ./install # then open https://<your-host>/admin
Requirements: 1 or 3 Linux nodes (Ubuntu 22.04/24.04, RHEL/Rocky 9, Debian 12),
SSH access with sudo. That's it. Single machine instead? Use examples/single-node.yml —
same flow, no HA. Full install guide →
We do not list an upgrade path we have not run
Rolling for patch releases (zero downtime, measured), stop-start for minor versions (sessions survive in PostgreSQL). Every supported path re-runs nightly in public CI: install the old version, log in, upgrade — the pre-upgrade session must still refresh. Ask any vendor for the probe log. Here's ours →
$ ./upgrade --to 26.7
Supported paths, strategies and measured windows: the upgrade table · live runs: nightly upgrade matrix
Drills, not promises
The distribution ships with drills that prove the failure modes you actually fear. Run them on your cluster whenever you like — CI runs the install and session drill on every commit.
$ ./verify --drill failover # Patroni switchover + write through the LB $ ./verify --drill restore # pgBackRest restore to a scratch directory $ ./verify --drill session # rolling restart; logins must survive
What it doesn't do (yet)
Air-gapped bundle
Planned — offline install bundles with all artifacts are part of the upcoming per-node subscription. Today the installer downloads artifacts at deploy time.
Single node → HA growth
Growing from a single node to a 3-node cluster means a fresh 3-node install plus a realm import. Start with ha-3node.yml if HA is where you're headed.
Everything else we claim is on the evidence ledger, with receipts.