Run Keycloak in Docker in 15 minutes

TL;DR

Pull the official Keycloak image, run one docker run command with your admin credentials, and you'll have Keycloak's admin console running on localhost:8080 in under two minutes. This guide covers development mode only — see the Docker Compose guide before running anything in production.

What you'll need

• Docker installed and running (docker --version should return something)
• A terminal
• Nothing else — Keycloak's Docker image includes everything

Step 1 — Pull and run the image

Run this in your terminal:

docker run -d \
  --name keycloak \
  -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=changeme \
  quay.io/keycloak/keycloak:latest \
  start-dev

What each part does:

Flag	What it does
-d	Run in the background (detached)
--name keycloak	Give the container a memorable name
-p 8080:8080	Map port 8080 on your machine to port 8080 in the container
KEYCLOAK_ADMIN	Username for the admin account
KEYCLOAK_ADMIN_PASSWORD	Password for the admin account — change this
start-dev	Start in development mode (uses an in-memory database, disables HTTPS requirement)

Step 2 — Check it started

docker logs keycloak

Wait until you see a line containing Keycloak ... started. It usually takes 20–40 seconds on first run.

Step 3 — Open the admin console

Open your browser and go to: http://localhost:8080

Click Administration Console, then log in with the username and password you set above (admin / changeme).

You're in. The master realm dashboard is what you're looking at.

Step 4 — Stop and remove the container

docker stop keycloak
docker rm keycloak

Because this runs in development mode with an in-memory database, everything you create is lost when the container stops. That's fine for exploring — it's not fine for anything real.

Common pitfalls

Port 8080 already in use. Something else is listening on 8080. Either stop it, or change the left side of -p to another port, e.g. -p 8180:8080, then visit localhost:8180.

"start-dev" is not for production. Development mode disables HTTPS and uses an in-memory H2 database. Data is lost every restart. Use Docker Compose with PostgreSQL for anything persistent — see the next guide.

Container starts but nothing loads. Give it another 30 seconds. Keycloak is a JVM application and takes time to warm up, especially on ARM (Raspberry Pi).

Wrong image name. The official image is quay.io/keycloak/keycloak — note quay.io, not Docker Hub. Using the wrong image will get you an old, unofficial build.

Where to go next

• Run Keycloak and PostgreSQL together with Docker Compose — persistent storage, ready for real use
• Create your first Keycloak realm and add users