Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 37 ยท Getting Started

Running Keycloak with Docker: Your First Server

Start Keycloak in a container in dev mode, create the bootstrap admin, persist data with a volume, find the URLs and fix common start-up problems.

The quickest way to meet Keycloak is a container. One command downloads the image, starts the server and gives you an admin console in your browser. This lesson shows the exact commands, explains every part and warns you about the two things beginners trip over: dev mode is not for production, and data disappears with the container unless you persist it.

Keycloak cannot run on this website, so the commands below are for your own machine. You need Docker (Docker Desktop on Windows and macOS, Docker Engine on Linux) and a few hundred megabytes of free disk. The commands are read-only snippets, but the two runnable blocks assemble and check them for you.

The one-line start

Terminal
docker run --name keycloak-dev -p 127.0.0.1:8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=change-me-now \
  quay.io/keycloak/keycloak:26.4 start-dev

Part by part:

Part Meaning
--name keycloak-dev A name so you can stop and start it later
-p 127.0.0.1:8080:8080 Publish port 8080, only on your own machine (the 127.0.0.1 part keeps other computers out)
KC_BOOTSTRAP_ADMIN_USERNAME / _PASSWORD Create the first admin user, in the master realm, on the first start only
quay.io/keycloak/keycloak:26.4 The official image. Use a current 26.x tag from the Keycloak download page and always pin a version rather than latest
start-dev Development mode

On older versions (before 26) the variables were named KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD. Keycloak is ready when the log says it started in a few seconds and lists a profile of dev. Then open http://localhost:8080 and sign in with the admin user you set.

What start-dev does

Development mode is a convenient bundle of settings:

  • plain HTTP is allowed (no certificate needed),
  • an embedded, file-based H2 database is used,
  • theme and cache settings favour fast change over speed,
  • hostname checks are relaxed.

That is perfect for learning and wrong for anything real. For production you use start with a real database, HTTPS and a configured hostname (see Configuring the Keycloak Server and the deployment chapter).

Keeping your data

A container's file system is thrown away when the container is removed. Keycloak's H2 data lives in /opt/keycloak/data, so mount a volume there:

Terminal
docker volume create keycloak-data

docker run --name keycloak-dev -p 127.0.0.1:8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=change-me-now \
  -v keycloak-data:/opt/keycloak/data \
  quay.io/keycloak/keycloak:26.4 start-dev

Now docker stop keycloak-dev and docker start keycloak-dev keep your realms, users and clients. The bootstrap variables only matter when the database is empty; changing them later does not change the admin password (reset it in the console or with a new temporary admin, see the operations chapter).

Useful container commands

Terminal
docker logs -f keycloak-dev        # follow the log
docker stop keycloak-dev           # stop
docker start keycloak-dev          # start again with the same data
docker rm -f keycloak-dev          # delete the container (volume stays)
docker volume rm keycloak-data     # delete the data too

The URLs worth knowing

URL (default dev setup) What it is
http://localhost:8080/ Welcome page, links to the admin console
http://localhost:8080/admin/ Admin console (redirects to the master realm)
http://localhost:8080/realms/master/account The Account Console, where a user manages their own profile
http://localhost:8080/realms/{realm}/.well-known/openid-configuration OIDC discovery document for a realm
http://localhost:9000/health/ready Health check on the management port 9000, only if health is enabled

Old tutorials mention an /auth prefix (/auth/realms/...). That belongs to the older WildFly-based Keycloak; the current Quarkus-based server has no prefix unless you configure one.

Docker Compose version

Most developers keep this in a compose.yaml so the setup is one docker compose up away:

YAML
services:
  keycloak:
    image: quay.io/keycloak/keycloak:26.4
    command: start-dev
    environment:
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: change-me-now
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - keycloak-data:/opt/keycloak/data

volumes:
  keycloak-data:

A command builder (stand-in)

Typing long commands by hand invites typos. This runnable stand-in builds the docker run command from a small configuration and refuses unsafe choices. It is plain JavaScript, not part of Keycloak, but it encodes the rules from this lesson.

Node.js Stand-in: build and lint a docker run command

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Reading the start-up log

Healthy start-up prints lines similar in spirit to these (exact wording changes by version): the Keycloak version, the Quarkus version, the profile (dev), the HTTP listener on port 8080 and a warning that dev mode is not for production. If you see none of them, check the next section.

Troubleshooting

  • Port already in use. Another program owns 8080. Change the left side of the mapping, for example -p 127.0.0.1:8180:8080, and open http://localhost:8180.
  • "Invalid username or password" right after the first start. The admin user is only created when the database is empty. If you reused a volume from an earlier run, the old password still applies.
  • The container exits immediately. Run docker logs keycloak-dev. A typo in start-dev, an unsupported option, or a read-only data volume are common causes.
  • The page loads but styles are broken behind a proxy. The hostname or proxy settings do not match the public URL; this is a production topic covered later.
  • Out of memory. Keycloak needs memory. Give Docker at least 2 GB.

A quick port checker (stand-in)

When a start fails, it helps to know which published ports of your plan clash. This stand-in checks a plan for duplicate host ports, something Docker reports only at start time.

Node.js Stand-in: detect clashing ports in a plan

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the -p 127.0.0.1:8080:8080 option accomplish?

    Prefixing the host side with 127.0.0.1 binds it to the loopback interface, so other machines cannot reach your dev server.
  2. 2. Why must you add a volume for /opt/keycloak/data in dev mode?

    H2 stores its files inside the container; a volume keeps them across container removal.
  3. 3. Which statement about start-dev is true?

    start-dev allows HTTP and uses an embedded database; production uses start with HTTPS and a real database.
  4. 4. You changed KC_BOOTSTRAP_ADMIN_PASSWORD and restarted with the same volume, but the old password still works. Why?

    The bootstrap admin is created only for an empty database. Later changes happen in the console.

Summary

  • docker run ... quay.io/keycloak/keycloak:<tag> start-dev gives a working server on port 8080 in a minute.
  • Bootstrap the admin with KC_BOOTSTRAP_ADMIN_USERNAME and KC_BOOTSTRAP_ADMIN_PASSWORD; it only applies to an empty database.
  • Mount a volume at /opt/keycloak/data to keep dev data; bind the port to 127.0.0.1.
  • Dev mode is for learning; production needs start, HTTPS, a real database and a hostname.
  • The current server has no /auth prefix; discovery lives at /realms/{realm}/.well-known/openid-configuration.

Next: A Tour of the Admin Console