Running Keycloak on Docker for the First Time

Introduction

Keycloak is an open-source identity and access management solution designed for modern applications and services. It offers features like single sign-on (SSO), social login, and user federation, making it a powerful tool for managing user identities across various platforms. Running Keycloak on Docker allows you to easily deploy and manage your identity management solution in a containerized environment, ensuring portability and scalability.

I came across Keycloak when I was working on a personal project and wondered how many times I had written authentication logic over the years. I concluded there had to be a solution that I could use that cross-cuts all basic authentication needs I might have(because looking back, the difference between all the auth services I've written for different apps was small). This would allow me to get started quicker with new projects as I wouldn't have to think authentication as much. Also, an added advantage I realised was better security - keycloak is written with best practices in mind, and since it is maintained by the community, all I have to do is pull new updates as required.

In this guide, we’ll walk you through the steps to run Keycloak on Docker for the first time.

Prerequisites

Before you begin, ensure that you have the following installed on your machine:

Docker: Install Docker from the official Docker website.
Docker Compose (optional): While not strictly necessary, Docker Compose simplifies managing multi-container Docker applications.
Step 1: Pull the Keycloak Docker Image

The first step is to pull the official Keycloak Docker image from the Docker Hub. This image contains everything you need to run Keycloak.

Open your terminal and run the following command:

docker pull quay.io/keycloak/keycloak:latest

This command pulls the latest Keycloak image from the Quay.io repository.

Step 2: Running Keycloak as a Standalone Container

To run Keycloak as a standalone container, execute the following command:

docker run -d -p 8080:8080 --name keycloak \
-e KEYCLOAK_ADMIN=admin \
-e KEYCLOAK_ADMIN_PASSWORD=admin_password \
quay.io/keycloak/keycloak:latest start-dev

Let’s break down the command:

-d: Runs the container in detached mode (in the background).
-p 8080:8080: Maps port 8080 of the container to port 8080 on your host machine.
--name keycloak: Names the container "keycloak".
-e KEYCLOAK_ADMIN=admin: Sets the Keycloak admin username.
-e KEYCLOAK_ADMIN_PASSWORD=admin_password: Sets the Keycloak admin password.
quay.io/keycloak/keycloak:latest start-dev: Specifies the image and starts Keycloak in development mode.
Once the container starts, you can access Keycloak by navigating to http://localhost:8080 in your web browser. You’ll be prompted to log in using the admin credentials you specified in the command.

Step 3: Running Keycloak with Docker Compose (Optional)

If you prefer using Docker Compose to manage your containers, you can create a docker-compose.yml file for Keycloak:

yaml
version: '3'

services:
  keycloak:
    image: quay.io/keycloak/keycloak:latest
    ports:
      - "8080:8080"
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin_password
    command:
      - start-dev

Save this file and run the following command to start Keycloak:

docker-compose up -d

This command will start Keycloak as a background service, making it easier to manage along with other services.

Step 4: Accessing the Keycloak Admin Console

With Keycloak up and running, you can now access the admin console. Open your web browser and navigate to http://localhost:8080. Log in using the admin credentials you set earlier.

Once logged in, you can start configuring realms, clients, users, and other Keycloak settings according to your needs.

Step 5: Stopping and Removing the Keycloak Container

To stop the Keycloak container, run:

docker stop keycloak

To remove the container, use:

docker rm keycloak

If you used Docker Compose, you can stop and remove the containers with:

docker-compose down

Conclusion

Running Keycloak on Docker is a straightforward process that allows you to quickly set up a robust identity and access management solution. With Docker's containerization, you can easily manage, scale, and deploy Keycloak across different environments. Whether you're running it as a standalone container or using Docker Compose for a more complex setup, Keycloak on Docker offers a flexible and powerful solution for your identity management needs.