Deploy and Host Keycloak on Railway

Keycloak is an open-source identity and access management server maintained under the Cloud Native Computing Foundation. It adds single sign-on to your apps over OpenID Connect, OAuth 2.0 and SAML, with user federation (LDAP and Active Directory), social and external identity providers, multi-factor authentication, and admin and account consoles.

About Hosting Keycloak

Hosting Keycloak means running its Java server in production mode next to a database, behind a TLS-terminating proxy. This template runs the official Keycloak 26.8.2 image with Railway's PostgreSQL 18 on the private network. Keycloak trusts Railway's forwarded headers, so its public URL, issuer and redirects use your HTTPS domain. A bootstrap admin account is created on first start with a generated password. All realms, users, clients and sessions are stored in Postgres, which keeps its data on a Railway volume. The first start takes about a minute while Keycloak builds its configuration and creates the database schema.

Common Use Cases

Single sign-on for internal tools and self-hosted apps over OpenID Connect or SAML
Login, registration, password reset and MFA for your own web or mobile app
A central identity broker in front of Google, GitHub, Microsoft or an LDAP/Active Directory directory

Dependencies for Keycloak Hosting

PostgreSQL (included, with a volume for its data)
A public HTTPS domain (Railway generates one for the Keycloak service)

Deployment Dependencies

Keycloak 26.8.2 release: https://github.com/keycloak/keycloak/releases/tag/26.8.2
Keycloak container guide: https://www.keycloak.org/server/containers
Reverse proxy settings: https://www.keycloak.org/server/reverseproxy
Hostname settings: https://www.keycloak.org/server/hostname
Database settings: https://www.keycloak.org/server/db
Health checks: https://www.keycloak.org/observability/health
All configuration options: https://www.keycloak.org/server/all-config

Implementation Details

First sign-in: open your Railway domain, choose "Administration Console", and sign in as admin with the KC_BOOTSTRAP_ADMIN_PASSWORD value from the Keycloak service's Variables tab. Keycloak marks this bootstrap account as temporary, so create a permanent admin user in the master realm and then delete or disable the bootstrap one. Changing KC_BOOTSTRAP_ADMIN_PASSWORD after the first start has no effect.

Configuration: the start command runs kc.sh start (production mode) with these defaults, and any of them can be overridden by adding the variable to the Keycloak service:

KC_DB=postgres
KC_HTTP_ENABLED=true            # Railway terminates TLS
KC_PROXY_HEADERS=xforwarded
KC_HEALTH_ENABLED=true
KC_HTTP_MANAGEMENT_HEALTH_ENABLED=false   # /health/ready on the main port for Railway's health check
KC_CACHE=local                  # single instance
JAVA_OPTS_KC_HEAP=-Xms64m -Xmx1g -XX:MaxHeapFreeRatio=10 -XX:MinHeapFreeRatio=5

KC_HOSTNAME is set to https://${{RAILWAY_PUBLIC_DOMAIN}}. If you add a custom domain, change KC_HOSTNAME to it and redeploy. The template is set up for one replica. Before you scale out, set KC_CACHE=ispn and read Keycloak's caching guide. An idle instance uses about 0.8 GB of memory.

Why Deploy Keycloak on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Keycloak on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.