NewOut Plane raises funding, backed by Maza VenturesRead the announcement
DevTools

Keycloak

Overview

Deploy Keycloak on Out Plane — the enterprise-grade open-source identity and access management solution maintained by Red Hat. Keycloak provides single sign-on (SSO), user federation, identity brokering, and social login for your applications with support for OpenID Connect, OAuth 2.0, SAML 2.0, and LDAP protocols.

Keycloak includes a comprehensive admin console for managing users, roles, groups, and clients. It supports two-factor authentication, brute-force protection, password policies, and fine-grained authorization services. Self-hosting on Out Plane ensures your identity data and authentication flows remain under your control.

Ideal for enterprises and SaaS platforms that need centralized identity management, SSO across multiple applications, user federation with Active Directory or LDAP, and social login integration with Google, GitHub, and other providers.


Keycloak Docker: Run Self-Hosted Keycloak in Production

Updated

Keycloak is an open source identity and access management server that adds single sign-on to your apps over OpenID Connect, OAuth 2.0 and SAML 2.0. To self-host it on Out Plane, run the official Keycloak Docker image, quay.io/keycloak/keycloak:26.8.2, with the start command on port 8080 and connect it to a managed PostgreSQL database. Keycloak recommends 2 GB of memory for a small production setup.

Most docker run and Docker Compose tutorials stop at start-dev. This guide covers what production mode adds: the hostname, the proxy headers, a JDBC URL with SSL, and a safe upgrade path. Every Keycloak setting below comes from the Keycloak server guides.

What You Need

  • An Out Plane plan. Starter and Pro both start with a 14-day free trial.
  • One app on op-34 (1 vCPU, 2.0 GB). The Keycloak image sizes the Java heap at 70 percent of container memory, and the containers guide recommends a 2 GB memory limit for smaller production deployments.
  • One managed PostgreSQL database. Keycloak 26.8 supports PostgreSQL 14 to 18, the same major versions Out Plane offers.
  • No volume. Realms, users, clients and sessions live in the database.

Use the official image from Quay. The Bitnami Keycloak images that rank on Docker Hub are no longer updated: bitnamilegacy/keycloak says so on its page and was last updated in August 2025.

Deploy Keycloak on Out Plane

The Deploy Keycloak button on the templates page opens the console. Nothing is filled in for you, so follow these steps.

  1. Create the database. Open Create → Database. Name it keycloak-db, keep version 17 (the default), and pick Europe (Frankfurt), the region closest to your app in Germany. Select Create database.
  2. Copy the connection details. On the database Overview, open the Connection panel and choose the .env format. Note PGHOST, PGDATABASE, PGUSER and PGPASSWORD.
  3. Create the app. Open Create → Application, choose the Image source and enter quay.io/keycloak/keycloak:26.8.2.
  4. Configure it. Set the name to keycloak and the Start command to /opt/keycloak/bin/kc.sh start. The start command runs as a direct exec and replaces the image's entrypoint, so write the full path.
  5. Pick the size. Under Compute, choose op-34 and 1 instance.
  6. Add the port. Add port 8080 with the HTTP scheme and make it public. The section previews your address, like https://keycloak-8080-yourteam.outplane.app.
  7. Add the variables. In Environment variables, paste this block with your own values:
bash
KC_DB=postgres
KC_DB_URL=jdbc:postgresql://PGHOST/PGDATABASE?sslmode=require
KC_DB_USERNAME=PGUSER
KC_DB_PASSWORD=PGPASSWORD
KC_HOSTNAME=https://keycloak-8080-yourteam.outplane.app
KC_HTTP_ENABLED=true
KC_PROXY_HEADERS=xforwarded
KC_BOOTSTRAP_ADMIN_USERNAME=temp-admin
KC_BOOTSTRAP_ADMIN_PASSWORD=use-a-long-random-password
  1. Deploy. Select Deploy app. The first start is slower, because Keycloak applies its build options and creates its tables.
  2. Sign in. Open /admin/ on your address and log in as temp-admin.

The same app from the outplane CLI, after you create the database in the console:

bash
outplane app create keycloak \
  --image quay.io/keycloak/keycloak:26.8.2 \
  --start-command "/opt/keycloak/bin/kc.sh start" \
  --port 8080:http:public \
  --size op-34 \
  --env KC_DB=postgres \
  --env "KC_DB_URL=jdbc:postgresql://PGHOST/PGDATABASE?sslmode=require" \
  --env KC_DB_USERNAME=PGUSER \
  --env KC_DB_PASSWORD=PGPASSWORD \
  --env KC_HOSTNAME=https://keycloak-8080-yourteam.outplane.app \
  --env KC_HTTP_ENABLED=true \
  --env KC_PROXY_HEADERS=xforwarded \
  --env KC_BOOTSTRAP_ADMIN_USERNAME=temp-admin \
  --env KC_BOOTSTRAP_ADMIN_PASSWORD=use-a-long-random-password

Keycloak Docker Configuration Explained

Each KC_ variable maps to a Keycloak option of the same name.

  • KC_DB=postgres selects the PostgreSQL driver. The default, dev-file, is a file database inside the container.
  • KC_DB_URL is a full JDBC URL. Out Plane databases require SSL, so keep sslmode=require. See the Keycloak database guide and the Out Plane database docs.
  • KC_HOSTNAME is the full public URL. Keycloak does not build its URLs from request headers by default. It uses this value in tokens, in the OpenID discovery document and in email links. See the hostname guide.
  • KC_HTTP_ENABLED=true opens the plain HTTP listener on 8080. Out Plane serves HTTPS at its edge and forwards HTTP to the port, which Keycloak calls edge TLS termination.
  • KC_PROXY_HEADERS=xforwarded tells Keycloak to read the X-Forwarded-* headers. The reverse proxy guide warns that without it, requests that check their origin fail with 403 Forbidden.
  • KC_BOOTSTRAP_ADMIN_* creates a temporary admin only on the very first start, when the master realm does not exist yet.

For faster starts, Keycloak suggests an optimized image built with kc.sh build and started with start --optimized. Put that Dockerfile in a GitHub repository and deploy the repository instead. The same route covers custom themes and providers.

After the First Login

  1. In the master realm, create a permanent admin user, set its password and give it the admin role.
  2. Sign in as that user and delete temp-admin. The admin console shows a warning banner until you do.
  3. Remove both KC_BOOTSTRAP_ADMIN_* variables in Settings → Environment. They have no effect after the first start.
  4. Create a separate realm for your apps. Keycloak's guide says to use master only for managing Keycloak.

Keycloak's proxy guide recommends keeping /admin/ and /realms/master/ off the public internet. On a public app, protect the master realm with strong passwords and OTP for admins.

Custom Domain and HTTPS

Set your final domain before you register any client. The hostname becomes the issuer in every token, so changing it later breaks clients that check the issuer.

  1. Open Domains → Add domain, enter auth.example.com, and pick the keycloak app and port 8080.
  2. Open the DNS dialog and add a CNAME to domains-management.outplane.app. For an apex domain, add the A record the dialog shows. HTTPS is issued automatically once DNS resolves, usually in 5 to 30 minutes.
  3. Change KC_HOSTNAME to https://auth.example.com and select Save & deploy.
bash
outplane domain add auth.example.com --app keycloak --port 8080
outplane domain dns auth.example.com
outplane env set KC_HOSTNAME=https://auth.example.com --app keycloak --deploy

Starter includes 5 custom domains and Pro includes 25.

Updates and Backups

Image apps never redeploy on their own. To upgrade, read the Keycloak upgrading guide, then deploy the new tag from Deployments → Deploy with the full image reference, or:

bash
outplane deploy create keycloak --image quay.io/keycloak/keycloak:NEW_VERSION --wait

Keycloak migrates the database schema when the new version starts and cannot roll it back. Deploying the old tag does not undo the migration. Only a database restore does, so take a dump before every upgrade. Since 26.6, Keycloak supports rolling updates for patch releases. For a minor or major upgrade, it asks you to stop the old version first, so plan a short maintenance window.

Managed PostgreSQL includes automated backups. For your own copy, run pg_dump from your machine with a client at least as new as the server:

bash
pg_dump "$(outplane db url keycloak-db)" -Fc -f keycloak-$(date +%F).dump

Keep the file somewhere you control, such as an Out Plane S3 compatible bucket. A kc.sh export does not replace it. Keycloak says export has limits as a backup tool and skips events and sessions.

Keycloak Hosting Cost on Out Plane

  • Compute: op-34 at $0.0004167 per instance-minute, or $18.00 for a 30-day month.
  • Database: $6.00 per month for managed PostgreSQL.
  • Storage: none, because Keycloak needs no volume. Bandwidth, SSL and custom domains are not billed.

That is $24.00 of usage a month. Starter costs $9 and includes $9 of usage, so the invoice is $24. Pro costs $29 and includes $15 of usage, so the invoice is $38. Both start with a 14-day free trial. Starter allows one managed database, which Keycloak would take. See pricing for every size.

FAQ

Can I deploy a Keycloak Docker Compose file on Out Plane?

Not as a file. Out Plane runs one image per app, so translate it service by service. The keycloak service becomes an image app with the settings above, and postgres becomes a managed PostgreSQL database. Move environment: into environment variables and command: into the start command after /opt/keycloak/bin/kc.sh.

Why not run start-dev?

Keycloak says to avoid development mode in production because of its insecure defaults. It also stores data in a dev-file database inside the container, which is lost when the instance is replaced.

How much memory does Keycloak need?

The containers guide recommends 2 GB for smaller production deployments and at least 750 MB to match the old 512 MB heap. op-34 gives you 2.0 GB.

Can I run more than one Keycloak instance?

Start with one. Keycloak nodes find each other through the database and then exchange cache data directly over TCP, so test a second instance before you rely on it. Starter allows one instance per app and Pro allows five.



Start deploying in minutes

Connect your GitHub repository and deploy your first application today. Start with a 14-day free trial.

Start 14-day free trial