Cloud and Self-Hosting

Keycloak Docker Installation: Run Keycloak 26 in Docker (Dev and Production)

Run Keycloak in Docker: the quay.io/keycloak/keycloak 26.8 image, start-dev for testing, and production Docker Compose with PostgreSQL and a proxy.

By Amjid Ali · · Updated · 4 min read

KeyCloak Docker Installation: SyncBricks cover
In this article
  1. Quick steps
  2. Step 1: Install Docker on Ubuntu
  3. Step 2: Run Keycloak in Docker (development mode)
  4. Step 3: Keycloak Docker Compose for production (PostgreSQL)
  5. Step 4: Reverse proxy and HTTPS
  6. Step 5: Create a realm, user and client
  7. Step 6: Back up Keycloak
  8. Troubleshooting

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

  1. Install Docker on the host (Ubuntu or any Linux).
  2. Test with start-dev and the bootstrap admin variables.
  3. For production, run Keycloak with PostgreSQL in Docker Compose using start.
  4. Put it behind a reverse proxy with HTTPS and expose only the public paths.
  5. Create a realm, a user and a client for your app.
  6. 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_ADMIN and KEYCLOAK_ADMIN_PASSWORD variables with KC_BOOTSTRAP_ADMIN_USERNAME and KC_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):

  • start runs production mode. Without --optimized Keycloak builds its configuration at startup, which is simpler but slower to start.
  • KC_DB, KC_DB_URL, KC_DB_USERNAME, KC_DB_PASSWORD point it at PostgreSQL.
  • KC_HOSTNAME is the public name users reach it on.
  • KC_HTTP_ENABLED plus KC_PROXY_HEADERS=xforwarded are needed when a reverse proxy terminates TLS and forwards X-Forwarded-* headers.
  • KC_HEALTH_ENABLED turns on /health, /health/ready and /health/live on 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

  1. Manage realms > Create realm, name it (for example homelab). Keep the master realm for administrators only.
  2. Users > Create new user, then Credentials > Set password with Temporary off.
  3. 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-dev for local tests.
  • Redirects go to http:// or the wrong host: set KC_HOSTNAME and KC_PROXY_HEADERS, and make sure the proxy sends X-Forwarded-Proto and X-Forwarded-Host.
  • Admin login does not exist after restart: in start-dev the 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

  1. Keycloak on Docker (getting started), Keycloak
  2. Running Keycloak in a container, Keycloak
  3. Configuring a reverse proxy, Keycloak
  4. Importing and exporting realms, Keycloak
  5. Install Docker Engine on Ubuntu, Docker