In this post, we will look at how to start the Keycloak server on your local machine in developer mode. This developer mode is not suitable or intended for use in a production environment. However, it is perfectly sufficient for our first experiments and local development.

The Keycloak server can be started standalone or via Docker. We will take a look at both options.

Run as a standalone server

The Keycloak Server is a Java-based Quarkus application. Therefore, the installation of a Java JDK is required to run the server. I recommend the latest Java LTS. This is Java 17 at the time of this post.

The Keycloak server can be downloaded from the official website or GitHub (Nightly builds are also available). At the time of writing this post, version 20.0.3 is current.

After downloading, unzip the file to a location of your choice. Then use a terminal to navigate into the unzipped folder. This may look similar to what I did:

wagnus@MacBook ~ % cd keycloak-20.0.3
wagnus@MacBook keycloak-20.0.3 % ls
LICENSE.txt     bin  lib  themes  README.md  conf  providers  version.txt

In the bin directory there is a script that can be used to start the server. If you are on a Mac or Linux please run the following command inside the keycloak folder:

bin/kc.sh start-dev --http-port 8181

If you are on windowsplease run the following command:

bin\kc.bat start-dev --http-port 8181

With start-dev the development mode is enabled. By default, the server runs on port 8080. If you want to start the server on a different port, you can use the --http-port parameter.

After some seconds you should see the final log message that indicates that the server is up and running:

[org.keycloak.quarkus.runtime.KeycloakMain] (main) Running the server in development mode. DO NOT use this configuration in production.

If you now go to http://localhost:8181 in your browser, you should see a welcome page from Keycloak.

Run as a docker image

If you prefer to run Keycloak as a Docker container, you can do so using the following command:

docker run \
--name keycloak \
-p 8181:8080 \
-e KEYCLOAK_ADMIN=administrator \
-e KEYCLOAK_ADMIN_PASSWORD=simsalabim \
quay.io/keycloak/keycloak:latest \
start-dev

Unlike when starting as a standalone server, a username and password for the administrator must be defined at the beginning via the environment variables KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD.

Attention: The Keycloak image from JBoss, which can be found on Docker Hub, does not have support for ARM-based chips such as Apple's M1 and M2 chip at the time of this post, so please use the image from quay.io/keycloak.

Create the initial admin user

If you have started Keycloak as a standalone server, then no administrator account exists yet. You have to create this account initially. Please open your browser and go to http://localhost:8181. On the left side of the welcome page, you can create the initial admin user.

If you have started Keycloak via docker you already have this initial admin account and no action is necessary.

This admin user is only used to manage the Keycloak server. Any number of client applications and users can be created with this user. It is the most powerful user type.

Login into the Administration console

Once the initial admin user is created, this option is no longer available on the welcome page. Instead, you have to log in to the Administration Console with the selected credentials.

After successfully entering your username and password you will get to the administration console of the Keycloak server:

Coming up next in this series

In this post, we looked at how to get Keycloak running on our local machine. In the next post, we'll dive deeper. We will setup our first realm and create our first client application with a user in it.