Dockerfile Keycloak: Building a Customized Keycloak Image for Your IAM Solution


In the world of Identity and Access Management (IAM), Keycloak has emerged as a popular open-source solution. It provides authentication, authorization, and management features to secure your applications and services. However, when deploying Keycloak, you may need to adapt it to your organization’s specific needs, such as integrating custom themes, extensions, or security configurations. This is where creating a customized Keycloak Docker image using a Dockerfile comes in handy. In this article, we will explore the process of creating a Dockerfile for Keycloak, and discuss how you can build and manage your custom Keycloak Docker image.

Why Customize Keycloak with a Dockerfile?

While Keycloak offers a wide range of out-of-the-box features, there might be scenarios where you need to modify the default settings or add your own customizations. Some of the reasons to customize Keycloak using a Dockerfile include:

  1. Meeting specific organizational requirements: Your organization may have unique requirements for user authentication, user interface, or data management that cannot be addressed by the standard Keycloak setup. In such cases, customizing Keycloak can help you align the IAM solution with your organization’s policies and workflows.
  2. Integrating custom themes and extensions: Keycloak supports custom themes for the login, account management, and administrative console pages. You may want to create a custom theme that matches your organization’s branding or introduces additional functionality. Additionally, you might need to add custom extensions, such as custom user storage providers, to integrate with your existing IT systems.
  3. Enhancing security configurations: Keycloak comes with a set of default security configurations that may not be suitable for all organizations. By customizing your Keycloak Docker image, you can strengthen the security settings, such as enabling HTTPS and configuring secure cookies, to better protect your applications and services.

Creating a Keycloak Dockerfile

To create a customized Keycloak Docker image, you need to write a Dockerfile that defines the steps to build the image. A Dockerfile is a script containing instructions for building a Docker image from a base image and applying customizations. In this section, we will walk through the process of creating a Dockerfile for Keycloak, starting with the official Keycloak base image and adding customizations as needed.

Starting with the Official Keycloak Base Image

To begin, we will use the official Keycloak base image available on Docker Hub as the foundation for our customized Keycloak Docker image. This ensures that we have a reliable, up-to-date, and well-maintained starting point for our customizations. In the Dockerfile, specify the base image using the FROM command:

FROM jboss/keycloak:<version> 

Replace <version> with the desired version of Keycloak you want to use.

Adding Custom Themes

To include custom themes in your Keycloak Docker image, first, create a directory to store your theme files. Then, use the COPY command in the Dockerfile to copy the theme directory from your local machine to the appropriate location within the Keycloak container:

COPY my-custom-theme /opt/jboss/keycloak/themes/my-custom-theme

After adding the custom theme, update the KEYCLOAK_IMPORT environment variable in the Dockerfile to configure Keycloak to use the new theme as the default:

ENV KEYCLOAK_IMPORT /opt/jboss/keycloak/themes/my-custom-theme/realm-export.json

Integrating Custom Extensions

To add custom extensions to your Keycloak Docker image, such as custom user storage providers or custom authenticators, use the COPY command in the Dockerfile to copy the extension JAR file from your local machine to the appropriate location within the Keycloak container:

COPY my-custom-extension.jar /opt/jboss/keycloak/standalone/deployments/my-custom-extension.jar

Configuring Security Settings

To enhance the security configurations of your Keycloak Docker image, you can update the Keycloak standalone.xml or standalone-ha.xml configuration files. For example, to enable HTTPS, first, create a custom configuration file with the required settings, and then use the COPY command in the Dockerfile to overwrite the default configuration:

COPY my-custom-standalone.xml /opt/jboss/keycloak/standalone/configuration/standalone.xml 

Building and Running the Customized Keycloak Docker Image

With the Dockerfile complete, you can build the custom Keycloak Docker image using the docker build command:

docker build -t my-custom-keycloak .

After building the image, use the docker run command to start a Keycloak container based on your custom image:

docker run -p 8080:8080 my-custom-keycloak

This will launch the Keycloak container and expose it on port 8080, allowing you to access the Keycloak instance and verify that your customizations are working as expected.

Managing Keycloak Configuration with Environment Variables

One of the key advantages of using Docker is the ability to manage and customize your application’s configuration using environment variables. This allows you to easily modify settings without having to rebuild the entire Docker image. In the context of Keycloak, you can configure various aspects of the IAM solution through environment variables.

Database Configuration

Keycloak supports multiple databases, and you can configure the connection details using environment variables. For example, to connect Keycloak with a PostgreSQL database, you can use the following environment variables when running the Docker container:

docker run -e DB_VENDOR=postgres -e DB_ADDR=<database-host> -e DB_PORT=<database-port> -e DB_DATABASE=<database-name> -e DB_USER=<database-user> -e DB_PASSWORD=<database-password> my-custom-keycloak

Replace the placeholders with the appropriate values for your PostgreSQL database.

SMTP Configuration

To configure Keycloak’s email settings for user notifications, such as password reset emails, use the following environment variables:

docker run -e KEYCLOAK_SMTP_HOST=<smtp-host> -e KEYCLOAK_SMTP_PORT=<smtp-port> -e KEYCLOAK_SMTP_USER=<smtp-user> -e KEYCLOAK_SMTP_PASSWORD=<smtp-password> my-custom-keycloak

Replace the placeholders with the appropriate values for your SMTP server.

Admin Console Configuration

To configure the Keycloak admin console, such as setting the initial admin user and password, use the following environment variables:

docker run -e KEYCLOAK_USER=<admin-user> -e KEYCLOAK_PASSWORD=<admin-password> my-custom-keycloak

Replace the placeholders with the desired admin username and password.

Scaling Keycloak with Docker Compose and Swarm

For production environments, you may need to scale your Keycloak instance to handle increased user loads and provide high availability. Docker Compose and Docker Swarm are two tools that can help you achieve this.

Docker Compose

Docker Compose allows you to define and manage multi-container applications. To use Docker Compose with Keycloak, create a docker-compose.yml file with the following contents:

version: '3'
image: my-custom-keycloak
- 8080:8080
- DB_VENDOR=postgres
- DB_ADDR=postgres
- DB_PORT=5432
- DB_DATABASE=keycloak
- DB_USER=keycloak
- DB_PASSWORD=keycloak
image: postgres
- POSTGRES_DB=keycloak
- POSTGRES_USER=keycloak

In this example, we define a Keycloak service and a PostgreSQL database service. Run the Docker Compose file using the following command:

docker-compose up 

This will start both the Keycloak and PostgreSQL containers and configure them to work together.

Docker Swarm

Docker Swarm is a native clustering and orchestration tool for Docker. To deploy Keycloak using Docker Swarm, you can use a similar docker-compose.yml file as described above. First, initialize the swarm:

docker swarm init

Then, deploy the Keycloak stack:

docker stack deploy -c docker-compose.yml keycloak 

This will create a Keycloak service and a PostgreSQL database service, which can be scaled and managed within the Docker Swarm cluster.

Customizing Keycloak Themes with Docker

When building a custom Keycloak image, you may want to include your own themes to personalize the look and feel of the login pages, account management console, and emails. Docker makes it easy to add custom themes to your Keycloak image.

Preparing Your Custom Theme

Before you can include your custom theme in the Docker image, ensure that it is properly structured. A Keycloak theme consists of a directory containing the following subdirectories:

  • login: This contains the resources for the login pages, such as HTML templates, stylesheets, and images.
  • account: This contains the resources for the account management console.
  • email: This contains the resources for email templates.

Modifying the Dockerfile to Include the Custom Theme

To include your custom theme in the Docker image, modify your Dockerfile as follows:

  1. Copy your custom theme directory into the image. Add the following line to your Dockerfile:
COPY <path-to-your-theme-directory> /opt/jboss/keycloak/themes/<your-theme-name>

Replace <path-to-your-theme-directory> with the path to your custom theme directory on your local machine, and <your-theme-name> with the desired name for your theme.

  1. Set the theme as the default theme for Keycloak. Add the following line to your Dockerfile:

Replace <your-theme-name> with the name of your theme.

  1. Build the Docker image with your custom theme:
docker build -t my-custom-keycloak-with-theme .

Monitoring and Logging Keycloak with Docker

Monitoring and logging are essential for maintaining the health and performance of your Keycloak instance. Docker provides a number of tools and integrations to help you monitor and log your Keycloak container.

Monitoring Keycloak with Docker Stats

Docker includes a built-in tool called docker stats that provides real-time resource usage statistics for your running containers. To monitor your Keycloak container, run the following command:

docker stats <container-id>

Replace <container-id> with the ID of your running Keycloak container. This command will display CPU usage, memory usage, network I/O, and block I/O statistics for your container.

Logging Keycloak with Docker Logs

Docker captures the standard output and standard error streams of your running containers and provides them through the docker logs command. To view the logs of your Keycloak container, run the following command:

docker logs <container-id>

Replace <container-id> with the ID of your running Keycloak container. This command will display the logs generated by Keycloak, including any error messages or diagnostic information.

Integrating Keycloak with External Monitoring and Logging Solutions

In addition to the built-in Docker monitoring and logging tools, you can also integrate your Keycloak container with external solutions such as Prometheus, Grafana, and the Elastic Stack (Elasticsearch, Logstash, and Kibana). These integrations can provide advanced monitoring, alerting, and visualization capabilities for your Keycloak instance.


In this guide, we explored how to build a custom Keycloak Docker image, including custom themes, and deploy it as an IAM solution. We also covered monitoring and logging your Keycloak Docker image. With these skills, you can effectively manage your Keycloak instance, ensuring its security, performance, and reliability.