Run Keycloak with Docker

The fastest way to run Keycloak locally is with Docker. The official image on quay.io includes everything you need — no separate database, no install steps. One command and Keycloak is listening on port 8080.

🔐 Run Keycloak with Docker first

Start Keycloak in dev mode:

docker run --name keycloak -p 8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:latest start-dev

Then open http://localhost:8080 and sign in to the admin console with admin / admin.

start-dev uses an in-memory database — perfect for learning. Use a real database and start for production.

The start-dev command explained

Here is what each part of the docker run command does:

1. docker run --name keycloak — names the container so you can reference it later with docker stop keycloak or docker rm keycloak.
2. -p 8080:8080 — maps port 8080 on the host to port 8080 inside the container, so http://localhost:8080 reaches Keycloak.
3. -e KC_BOOTSTRAP_ADMIN_USERNAME=admin — sets the initial admin username. This environment variable is only used on the very first boot when no admin account exists yet.
4. -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin — sets the initial admin password. Change this in any real environment — never leave it as admin outside of local dev.
5. quay.io/keycloak/keycloak:latest — the official Keycloak image from the Red Hat Quay registry. Pin to a specific version (e.g. 26.7) in CI or staging.
6. start-dev — starts Keycloak in development mode with an embedded H2 in-memory database and HTTP enabled. No TLS certificate is required.

docker run --name keycloak -p 8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:latest start-dev

Copy docker run ⧉

Opening the admin console

1. Wait for the log line that says Keycloak X.Y.Z on JVM (powered by Quarkus) started — this means Keycloak is ready.
2. Open http://localhost:8080 in your browser.
3. Click “Administration Console”.
4. Sign in with username admin and password admin.
5. You are now in the master realm’s admin console.

Admin console vs account console

The admin console (http://localhost:8080) is the management UI for administrators. You create realms, clients, users, roles, and identity providers here. Only team members who need to configure Keycloak should have access to it.

The account console (http://localhost:8080/realms/master/account) is the self-service portal for end users. Users can update their profile, change their password, and manage their active sessions here. Your application users land here, not the admin console. Each realm has its own account console at /realms/{realm-name}/account.

Stopping and removing the container

# Stop the container
docker stop keycloak
# Remove the container (data is lost — this is dev mode)
docker rm keycloak

Because start-dev uses an in-memory H2 database, all realms, clients, and users you created are gone when the container is removed. In the next module you will learn how to persist data with an external database.

🔐 start-dev is for learning only

start-dev disables important production checks and uses an in-memory database. All data is lost when the container stops. Never use start-dev in production — use start with an external database instead.

Trade-offs

Option	Benefit	Cost
start-dev in a Docker container	Up and running with one command, no database setup needed — good for experimenting and learning	Data is lost every time the container is removed, there’s no TLS, and it’s not fit for a real workload, even staging
start with an external database (production mode)	Data persists across restarts/redeploys, supports TLS and a fixed hostname, and scales across multiple instances	Requires setting up a database, TLS certificate, and reverse proxy before it can be used

Common mistakes

• Running start-dev and forgetting to switch to start before going to production — start-dev disables several security checks and uses an in-memory database; forgetting to switch modes means production data disappears the moment the container restarts.
• Not changing KC_BOOTSTRAP_ADMIN_USERNAME/KC_BOOTSTRAP_ADMIN_PASSWORD from the default — leaving admin/admin in place, even in a container exposed to another network, is a very common security gap.
• Not pinning the image version — using quay.io/keycloak/keycloak:latest in CI or staging causes behaviour to change unexpectedly whenever a new version is released. Always pin to a specific version.

Real-world example

Platform engineering teams inside an organisation — commonly use docker run start-dev or docker-compose only on a developer’s local machine for integration testing, then deploy the real Keycloak through a Helm chart on Kubernetes with an external PostgreSQL database.

Red Hat build of Keycloak (RH-SSO) — the image used in this lesson is the community build; organisations that need an SLA-backed support contract use the Red Hat build of Keycloak container image instead, but the start/start-dev commands and environment variables work the same way.

What does the -p 8080:8080 flag do in the docker run command?

Sets the admin password to 8080 Maps port 8080 on the host to port 8080 in the container Allocates 8080 MB of memory Exposes port 8080 only to other containers

Which database does start-dev use?

PostgreSQL MySQL An embedded H2 in-memory database SQLite

What is the difference between the admin console and the account console?

They are the same thing The admin console is for administrators to manage Keycloak; the account console is for end users to manage their profile The account console requires a separate installation The admin console is only available on port 9090

What happens to your data when you docker rm the Keycloak container in start-dev mode?

Data is automatically backed up Data persists because it is stored in the image All data is lost — start-dev uses an in-memory database Data is saved to /tmp on the host

Submit

Mark as complete