Keycloak is an open source project that is a convenient option for delegating authentication and user management. It allows us to focus more on delivering business value to our projects. A proper Docker configuration for this service will come in handy whenever we need to run it locally.
- Docker installed on your machine. You can check the installed version with the
docker --versioncommand. The command’s output on my environment at the moment of writing this post is as follows:
- The starting point for the work presented in this post is contained in the commit 34f8178e23b3bb05da30a7b247cd5f3dc4110c4d.
How to configure Docker containers for Keycloak
Below you’ll find the content of my
.env file specifying the default environment variables for those services:
The COMPOSE_PROJECT_NAME variable holds a prefix for the services names. You’ll see the resulting names later in this post. You can provide the name of your project as a value for this variable.
Keycloak container configuration explained
Let’s take a look at the properties configured in the
On my machine, the
port 8080 is already taken by another service. Therefore, I’m going to expose the keycloak service on port 8024 using the HOST:CONTAINER format.
Below you’ll find a short explanation for the variables that we’re going to set.
KEYCLOAK_USER and KEYCLOAK_PASSWORD
We’re specifying credentials to create an
admin account in the
keycloak service. As we can read in the image documentation:
By default there is no admin user created so you won’t be able to login to the admin console. To create an admin account you need to use environment variables to pass in an initial username and password.https://hub.docker.com/r/jboss/keycloak
An alternative to passing the credentials directly as environment variables is to provide them via files. Use the
KEYCLOAK_PASSWORD_FILE variables if you want to keep the values in files.
An optional variable for specifying name of the database. Defaults to
An optional variable for specifying a user used to authenticate to the database. Defaults to
An optional variable for specifying a user password used to authenticate to the database. Defaults to
An optional variable for specifying a
hostname for the database. Because we’re going to run the
keycloak services in a common
internal network in Docker, we need to provide the service name here –
keycloakdb in my example. Keycloak will add the default port 5432 to that hostname. So the resulting host will be
keycloakdb:5432. On the other hand, you can specify a custom port by setting the DB_PORT variable as well.
An optional variable for specifying a database vendor. If absent, Keycloak tries to determine the database on its own. If this process fails, Keycloak defaults to using H2. Consult the image documentation to see what values are supported. For our PostgreSQL database I’m going to use the
You can find a detailed explanation on how to run a PostgreSQL database as a dockerized service in the Set up a PostgreSQL database with Docker post. Therefore, I won’t be repeating the configuration and variables description in this article. It’s important to realize that you’re not limited to the PostgreSQL database. As we can read in the image documentation:
This image supports using H2, MySQL, PostgreSQL, MariaDB, Oracle or Microsoft SQL Server as the database.
(…) If the DB can’t be detected it will default to the embedded H2 database.https://hub.docker.com/r/jboss/keycloak
On my machine, the
port 5432 is already taken by another service. Therefore, I’m going to expose the keycloak database on port 5433 using the HOST:CONTAINER format.
We’re going to create the named
keycloak-postgres volume on our machine that will store content of the
/var/lib/postgresql/data directory in the container.
Start Keycloak service as Docker containers
Finally, we’re going to run the following command:
As a result, we can see two Docker services running on our machine:
Moreover, we’ll see that the
keycloakindocker specified in the COMPOSE_PROJECT_NAME variable was added as a name prefix.
Additionally, in the
keycloak container logs, we’ll see that the service is using our PostgreSQL database and not the default H2:
First, we’re going to visit the http://localhost:8024/auth/ url where we’ll find the Keycloak
Next, we’re going to select the
Administration Console option. In order to log in, we’ll need to enter our default credentials in the following form:
According to the default environment variables from my
.env file, my credentials are:
Finally, after a successful authentication, Keycloak redirects us to the master realm, a pre-defined realm that Keycloak created for us:
In summary, the work presented in this article is contained in the 05e4c72e4a01f33304b45e8410352060e1a17044 commit.