keycloak docker compose

Poolie Author

2 min read

·

09-03-2025

3

0

Share

Running Keycloak with Docker Compose: A Simple Guide

Keycloak, a widely-adopted open-source Identity and Access Management (IAM) solution, simplifies user authentication and authorization. Setting up Keycloak traditionally involves several steps, but using Docker Compose streamlines the process considerably. This article provides a straightforward guide to deploying Keycloak using Docker Compose, making it easy to get started with this powerful tool.

What is Docker Compose?

Docker Compose is a tool for defining and running multi-container Docker applications. It allows you to define your application's services (like Keycloak in our case) in a single YAML file, simplifying the process of setting up and managing the application's environment.

Setting up Keycloak with Docker Compose

1. Prerequisites:

   • Ensure you have Docker and Docker Compose installed on your system. You can download them from the official Docker website.
   • Basic familiarity with Docker and Docker Compose is helpful but not strictly required.

2. The docker-compose.yml file:

   Create a file named docker-compose.yml in your project directory with the following content:

   version: "3.9"
   services:
     keycloak:
       image: jboss/keycloak:latest
       ports:
         - "8080:8080"
         - "8443:8443"
       volumes:
         - ./keycloak/data:/opt/jboss/keycloak/data
         - ./keycloak/themes:/opt/jboss/keycloak/themes
       environment:
         - KEYCLOAK_USER=admin
         - KEYCLOAK_PASSWORD=admin
   

   This configuration defines a single service, keycloak, using the official Keycloak Docker image. Let's break down the important parts:

   • image: jboss/keycloak:latest: Specifies the Keycloak Docker image to use. latest pulls the newest version. Consider using a specific tag (e.g., 18.0.1) for better reproducibility.
   • ports: ...: Maps the Keycloak ports (8080 for HTTP, 8443 for HTTPS) to your host machine.
   • volumes: ...: This is crucial. It defines persistent storage for Keycloak's data and themes. Creating the directories ./keycloak/data and ./keycloak/themes before running the command is essential to avoid errors. These volumes ensure your Keycloak configuration and data persist even if the container is stopped and restarted.
   • environment: ...: Sets the initial admin username and password. Remember to change these to strong, secure credentials in a production environment.

3. Running Keycloak:

   Navigate to the directory containing your docker-compose.yml file in your terminal and run:

   docker-compose up -d
   

   The -d flag runs Keycloak in detached mode (in the background).

4. Accessing Keycloak:

   Once the containers are running, you can access Keycloak in your browser at http://localhost:8080 or https://localhost:8443. Use the admin credentials you specified in the docker-compose.yml file.

5. Stopping Keycloak:

   To stop Keycloak, run:

   docker-compose down
   

Customization and Advanced Configurations:

• Specific Keycloak Version: Replace latest with a specific version tag in the image parameter for consistent results.
• Database Configuration: For persistent storage beyond the default in-memory database, you'll need to configure a database (like PostgreSQL or MySQL) as a separate service in your docker-compose.yml file and connect Keycloak to it.
• Custom Themes: Place custom themes in the ./keycloak/themes directory.
• Advanced Configuration Options: Refer to the official Keycloak documentation for more advanced configuration options using environment variables.

Conclusion:

Using Docker Compose dramatically simplifies the process of setting up and managing a Keycloak instance. This guide provides a solid foundation for getting started; further exploration of Keycloak's extensive features will empower you to build robust and secure authentication systems for your applications. Remember to always prioritize security best practices, especially when handling sensitive credentials.