Cloud and Self-Hosting
Keycloak Docker Installation: Run Keycloak 26 in Docker (Dev and Production)
By Amjid Ali · · Updated · 4 min read

In this article
To run Keycloak in Docker, start the official image quay.io/keycloak/keycloak with an initial admin user: docker run -p 127.0.0.1:8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.8.1 start-dev, then open http://localhost:8080/admin. That is development mode. For production, use the start command with PostgreSQL, a hostname and HTTPS (directly or through a reverse proxy), as in the Docker Compose example below.
This guide is updated for Keycloak 26.8.1, the current release on keycloak.org in October 2026. I use Keycloak in my homelab for single sign-on in front of self-hosted apps, and the steps below follow the official Keycloak container documentation.
Quick steps
- Install Docker on the host (Ubuntu or any Linux).
- Test with
start-devand the bootstrap admin variables. - For production, run Keycloak with PostgreSQL in Docker Compose using
start. - Put it behind a reverse proxy with HTTPS and expose only the public paths.
- Create a realm, a user and a client for your app.
- Back up the database.
Step 1: Install Docker on Ubuntu
You do not need Java on the host; the Keycloak image includes it. Install Docker Engine with Docker's official instructions, or on a lab machine use the convenience script:
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo docker version
New to containers? Start with Docker for beginners.
Step 2: Run Keycloak in Docker (development mode)
docker run -p 127.0.0.1:8080:8080 \
-e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
-e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
quay.io/keycloak/keycloak:26.8.1 start-dev
Open http://localhost:8080/admin and sign in as admin. The 127.0.0.1: prefix keeps the port on the local machine only; drop it if you test from another computer on a trusted network.
start-dev uses an embedded H2 database inside the container, so everything is lost when the container is removed. Use it to learn, not to keep users.
Keycloak 26 replaced the old
KEYCLOAK_ADMINandKEYCLOAK_ADMIN_PASSWORDvariables withKC_BOOTSTRAP_ADMIN_USERNAMEandKC_BOOTSTRAP_ADMIN_PASSWORD. The bootstrap admin is meant to be temporary: create a permanent admin and delete it.
Step 3: Keycloak Docker Compose for production (PostgreSQL)
Create a folder and a compose.yaml:
services:
postgres:
image: postgres:17
restart: unless-stopped
environment:
POSTGRES_DB: keycloak
POSTGRES_USER: keycloak
POSTGRES_PASSWORD: change-this-db-password
volumes:
- pgdata:/var/lib/postgresql/data
keycloak:
image: quay.io/keycloak/keycloak:26.8.1
command: start
restart: unless-stopped
depends_on:
- postgres
environment:
KC_DB: postgres
KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
KC_DB_USERNAME: keycloak
KC_DB_PASSWORD: change-this-db-password
KC_HOSTNAME: auth.example.com
KC_HTTP_ENABLED: "true"
KC_PROXY_HEADERS: xforwarded
KC_HEALTH_ENABLED: "true"
KC_BOOTSTRAP_ADMIN_USERNAME: admin
KC_BOOTSTRAP_ADMIN_PASSWORD: change-this-admin-password
ports:
- "127.0.0.1:8080:8080"
volumes:
pgdata:
Start it and follow the log:
docker compose up -d
docker compose logs -f keycloak
What each setting does (from the container guide and reverse proxy guide):
startruns production mode. Without--optimizedKeycloak builds its configuration at startup, which is simpler but slower to start.KC_DB,KC_DB_URL,KC_DB_USERNAME,KC_DB_PASSWORDpoint it at PostgreSQL.KC_HOSTNAMEis the public name users reach it on.KC_HTTP_ENABLEDplusKC_PROXY_HEADERS=xforwardedare needed when a reverse proxy terminates TLS and forwardsX-Forwarded-*headers.KC_HEALTH_ENABLEDturns on/health,/health/readyand/health/liveon the management port 9000.
Optional: an optimized image
For faster starts, build a custom image as the docs show:
FROM quay.io/keycloak/keycloak:26.8.1 AS builder
ENV KC_HEALTH_ENABLED=true
ENV KC_DB=postgres
RUN /opt/keycloak/bin/kc.sh build
FROM quay.io/keycloak/keycloak:26.8.1
COPY --from=builder /opt/keycloak/ /opt/keycloak/
ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]
Then run it with start --optimized.
Step 4: Reverse proxy and HTTPS
Point your proxy (Nginx, Caddy, Traefik or Nginx Proxy Manager) at http://127.0.0.1:8080 for auth.example.com with a valid certificate. Keycloak's guide says to expose only /realms/, /resources/ and /.well-known/, keep /admin/ and /realms/master/ internal, and never expose /metrics, /health or port 9000. If you terminate TLS in Keycloak itself instead, use --https-certificate-file and --https-certificate-key-file (or a keystore) and publish port 8443.
Step 5: Create a realm, user and client
- Manage realms > Create realm, name it (for example
homelab). Keep themasterrealm for administrators only. - Users > Create new user, then Credentials > Set password with Temporary off.
- Clients > Create client, type OpenID Connect, set a client ID, keep Standard flow on, and add your app's redirect URI and web origin.
Your app then uses the realm's OpenID configuration at https://auth.example.com/realms/homelab/.well-known/openid-configuration.
Step 6: Back up Keycloak
All realms, users and clients live in PostgreSQL, so back up the database:
docker compose exec -T postgres pg_dump -U keycloak keycloak > keycloak-$(date +%F).sql
For a JSON realm export, Keycloak must be stopped first; then use kc.sh export --dir <path> --realm <realm> as the import and export guide describes. Do not rely on docker commit for backups: it does not capture data in volumes or the database.
Troubleshooting
- "HTTPS required" when logging in over HTTP: you are reaching a production instance without TLS. Use the proxy URL with HTTPS, or
start-devfor local tests. - Redirects go to
http://or the wrong host: setKC_HOSTNAMEandKC_PROXY_HEADERS, and make sure the proxy sendsX-Forwarded-ProtoandX-Forwarded-Host. - Admin login does not exist after restart: in
start-devthe H2 data was lost with the container; use the Compose setup with PostgreSQL. - Upgrading: change the image tag, back up the database, then
docker compose pull && docker compose up -d.
For a non-Docker install, see Keycloak installation on Ubuntu (older version). To place Keycloak in a bigger lab, read the homelab guide.
Frequently asked questions
How do I run Keycloak in Docker?+
Run docker run -p 127.0.0.1:8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.8.1 start-dev, then open http://localhost:8080/admin and log in. start-dev is for testing only; production needs the start command, a real database, a hostname and HTTPS.
What is the official Keycloak Docker image?+
The official image is quay.io/keycloak/keycloak on Quay.io, maintained by the Keycloak project. The old jboss/keycloak image on Docker Hub is no longer maintained and should not be used.
What is the difference between start-dev and start in Keycloak?+
start-dev runs Keycloak in development mode: HTTP enabled, no hostname required, caching relaxed and an embedded H2 database, so it is quick to try but not safe or durable. start runs in production mode: it expects HTTPS (or HTTP behind a proxy with http-enabled), a configured hostname and an external database such as PostgreSQL.
What is the default Keycloak admin username and password in Docker?+
There is none. You set the initial admin with the KC_BOOTSTRAP_ADMIN_USERNAME and KC_BOOTSTRAP_ADMIN_PASSWORD environment variables on first start. The older KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD variables were replaced in Keycloak 26. Create a permanent admin user afterwards and remove the bootstrap one.
Does Keycloak need Java installed when using Docker?+
No. The container image already includes the Java runtime Keycloak needs. You only need Docker (or Podman) on the host.
How do I back up Keycloak running in Docker?+
Back up the database, for example with pg_dump for PostgreSQL, which holds all realms, users and clients. For a realm export in JSON, stop Keycloak and run kc.sh export with --dir or --file and --realm, as the Keycloak import and export guide describes.
Sources
- Keycloak on Docker (getting started), Keycloak
- Running Keycloak in a container, Keycloak
- Configuring a reverse proxy, Keycloak
- Importing and exporting realms, Keycloak
- Install Docker Engine on Ubuntu, Docker
Keep reading
Cloud and Self-HostingZSvirt vs Proxmox VE 9 (2026): A Hands-On Comparison of the New Open-Source VMware AlternativeZSvirt vs Proxmox VE 9, tested on real hardware: stack, install, VM creation, UI, VMware migration and licensing compared, and which one to choose in 2026. · 5 min read
Cloud and Self-HostingHow to Deploy a Flexible VPS for Apps: Kamatera ReviewNeed to deploy a flexible VPS for apps without committing to a fixed server shape? This Kamatera review examines its configurable cloud servers, scaling options, trial… · 8 min read
Cloud and Self-HostingExchange Server to Microsoft 365 Migration: A Pre-Migration Readiness ChecklistWhat to check before moving Exchange Server mailboxes to Microsoft 365: environment, migration method, identity, mail flow, permissions, security, pilot and cutover. · 7 min read