Running Keycloak Locally

Table of Contents

1. What You Need
2. Run Keycloak with Docker
3. Open the Admin Console
4. Tour of the Admin Console
5. Create Our First Realm
6. Master Realm vs Application Realm
7. Beginner Pitfalls

We use Docker so this is reproducible on any machine — no manual Java or Keycloak install.

1. What You Need

• Docker (Docker Desktop, or the Docker Engine on Linux) — docker --version to check
• Nothing else. Keycloak's own container ships everything it needs to run in development mode.

2. Run Keycloak with Docker

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

• start-dev runs Keycloak in development mode — an embedded database, relaxed HTTPS requirements, and hot-reload-friendly defaults. Never use start-dev for a production deployment (see Part 8 for what production hardening involves).
• KC_BOOTSTRAP_ADMIN_USERNAME / KC_BOOTSTRAP_ADMIN_PASSWORD create the first admin account the first time the container boots.

Wait for a line like Keycloak … started in … Listening on: http://0.0.0.0:8080 — that's your signal it's ready.

3. Open the Admin Console

Visit http://localhost:8080, click Administration Console, and log in with the admin / admin credentials from the command above.

4. Tour of the Admin Console

The left sidebar is the whole mental model of Keycloak in one glance:

• Realm selector (top-left) — which realm you're currently managing
• Realm settings — the realm itself: tokens, login policy, themes
• Clients — applications registered against this realm
• Users — accounts inside this realm
• Realm roles — roles available realm-wide

Everything in Part 4 happens inside this sidebar.

5. Create Our First Realm

By default you land in the master realm — don't build inside it (see §6). Instead:

1. Click the realm selector (top-left, shows master)
2. Create realm
3. Name it crash-course
4. Create

You're now managing an isolated realm with zero users or clients — the starting point for Part 4.

6. Master Realm vs Application Realm

• master realm — created automatically, used to administer Keycloak itself (manage other realms, server-wide settings). It is not meant to hold your application's users.
• Application realm (crash-course, here) — where your app's actual users, clients, and roles live. Every real project gets its own realm, separate from master.

7. Beginner Pitfalls

• Building everything inside master. It works at first, but mixes your application's users with Keycloak's own administrators — always create a dedicated realm.
• Forgetting -p 8080:8080. Without the port mapping, the container runs but localhost:8080 connects to nothing.
• Using start-dev in production. It's explicitly for local/dev use — production needs a real database, HTTPS, and a hostname configuration, none of which start-dev sets up for you.

Official docs:

• Running Keycloak in a container