Home > Software > How to Set Up Keycloak with Docker Compose: A Detailed Guide

How to Set Up Keycloak with Docker Compose: A Detailed Guide

Anastasios Antoniadis

Share on X (Twitter) Share on Facebook Share on Pinterest Share on LinkedInKeycloak is an open-source Identity and Access Management solution for modern applications and services. It provides out-of-the-box support for managing users, credentials, roles, and federations, along with features like Single Sign-On (SSO) and Identity Brokering. Deploying Keycloak using Docker Compose simplifies setting up …

Docker (1)

Keycloak is an open-source Identity and Access Management solution for modern applications and services. It provides out-of-the-box support for managing users, credentials, roles, and federations, along with features like Single Sign-On (SSO) and Identity Brokering. Deploying Keycloak using Docker Compose simplifies setting up and managing Keycloak instances, especially in development and testing environments. This article provides a step-by-step guide to deploying Keycloak with Docker Compose, including a basic example configuration.

Prerequisites

Before you begin, ensure you have the following:

  • Docker and Docker Compose installed on your system.
  • Basic understanding of Docker and Docker Compose.
  • An available port on your machine for Keycloak and its database.

Step 1: Create a Docker Compose File

Start by creating a directory for your Keycloak project. This directory will contain your Docker Compose file (docker-compose.yml) and any additional configuration files or directories you might need.

mkdir keycloak-setup && cd keycloak-setup

Create a docker-compose.yml file in this directory:

touch docker-compose.yml

Open the file in your favorite text editor and add the following configuration:

version: '3.7'

services:
  keycloak-db:
    image: postgres:latest
    container_name: keycloak_db
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: password
    volumes:
      - db_data:/var/lib/postgresql/data

  keycloak:
    image: jboss/keycloak:latest
    container_name: keycloak_server
    environment:
      DB_VENDOR: POSTGRES
      DB_ADDR: keycloak-db
      DB_DATABASE: keycloak
      DB_USER: keycloak
      DB_PASSWORD: password
      KEYCLOAK_USER: admin
      KEYCLOAK_PASSWORD: admin
    depends_on:
      - keycloak-db
    ports:
      - "8080:8080"
    restart: always

volumes:
  db_data:

This configuration does the following:

  • Sets up a PostgreSQL database for Keycloak: Keycloak requires a database to store its data. Here, we’re using PostgreSQL, configured with a volume for data persistence.
  • Configures the Keycloak server: It connects to the PostgreSQL database and sets the initial admin user and password. The depends_on option ensures the database starts before Keycloak.
  • Exposes Keycloak on port 8080: This allows you to access the Keycloak admin console from your local machine.

Step 2: Launch Keycloak

Navigate to the directory containing your docker-compose.yml file and run the following command to start Keycloak and its database:

docker compose up -d

The -d flag runs the containers in detached mode, in the background.

Step 3: Access the Keycloak Admin Console

Once Keycloak is up and running, open a web browser and go to http://localhost:8080/auth. You should be redirected to the Keycloak welcome page. Click on the “Administration Console” link and log in using the admin credentials you set in the Docker Compose file (admin/admin in the example).

Step 4: Configure Keycloak

After logging in, you can start configuring realms, clients, users, and roles according to your needs. Keycloak’s comprehensive documentation provides detailed instructions for these steps.

Step 5: Managing Keycloak

To stop Keycloak and its database, use the following command:

docker-compose down

To update Keycloak to a newer version, update the version tag in your docker-compose.yml file and run:

docker-compose pull && docker-compose up -d

Conclusion

Deploying Keycloak with Docker Compose offers a straightforward and effective solution for setting up a robust Identity and Access Management system. Whether for development, testing, or production, this approach simplifies the management of Keycloak instances, ensuring a smooth and efficient setup process. Following the steps outlined in this guide, you can have a Keycloak server running on your machine, ready to secure your applications and services.

Anastasios Antoniadis
Follow me
0 0 votes
Article Rating
Subscribe
Notify of
guest
0 Comments
Inline Feedbacks
View all comments
0
Would love your thoughts, please comment.x
()
x