Deploying Keycloak 25 with PostgreSQL

In the modern software landscape, Identity and Access Management (IAM) is a critical pillar of security. Keycloak, an open-source solution maintained by Red Hat, has become the industry standard for handling authentication and authorization.

Below, we break down how to containerize Keycloak 25.0 using Docker Compose, ensuring a persistent and scalable environment.

1. The Architecture

To run Keycloak effectively, we need two main components:

1. Keycloak Application: The core engine that handles OIDC, SAML, and User Management.
2. PostgreSQL Database: A relational database to store realms, users, clients, and session data.

2. Configuration Breakdown

The docker-compose.yml File

This file defines our multi-container application. We use the latest Quarkus-based distribution of Keycloak (v25.0).

Key Environment Variables Explained

1. KC_HTTP_ENABLED: true: Since Keycloak defaults to HTTPS, this allows us to use plain HTTP for local development.
2. KC_HOSTNAME_STRICT: false: Disables strict hostname checking, which is helpful when running on localhost.
3. KC_DB: Tells Keycloak to use the PostgreSQL driver.
4. depends_on: Ensures the database container starts before Keycloak attempts to connect.

3. Managing Secrets with .env

To keep your credentials secure and your YAML file clean, we use a .env file. This prevents hardcoding sensitive information into your version control system.

File: .env

4. Deployment Steps

Once your files are prepared, follow these steps to launch your IAM stack:

1. Initialize the Containers: Open your terminal in the project directory and run: docker-compose up -d
2. Check Logs: Monitor the startup process to ensure the database is ready: docker-compose logs -f keycloak
3. Access the Console: Navigate to http://localhost:8080 in your browser. Use the credentials defined in your .env file to log into the Administration Console.

5. Security Note for Production

The configuration provided is optimized for development and testing. When moving to a production environment, ensure you:

1. Set KC_HTTP_ENABLED to false.
2. Configure SSL/TLS certificates.
3. Enable KC_HOSTNAME_STRICT.
4. Use complex, non-default passwords for the database and admin accounts.