How to Test Keycloak and PostgreSQL Upgrades Using Docker

by

Are you considering upgrading your Keycloak or PostgreSQL versions but worried about potential compatibility issues? This step-by-step guide will walk you through how to use Docker-compose to test different Keycloak versions against various PostgreSQL versions, ensuring a smooth and safe upgrade process.

Why Compatibility Testing is Crucial

Before diving into the technical process, it’s essential to understand why compatibility testing is a non-negotiable step in your upgrade strategy. Compatibility testing helps prevent unexpected downtime, data loss, and security vulnerabilities by identifying potential issues in a controlled environment. This blog aims to equip system administrators, DevOps engineers, and IT professionals with the knowledge to confidently upgrade their authentication systems.

You don’t want to be the guy who wipes out Production by mistake and have to bring back all the users.

Prerequisites

  • Docker and Docker-compose installed on your system.
  • Basic understanding of Docker concepts and commands.
  • A safe, non-production environment for conducting the tests 😉

Initial Setup with Keycloak and PostgreSQL

Our journey begins with setting up an environment that mirrors your current configuration. Suppose you’re running Keycloak version 11 with PostgreSQL version 11. Here’s how you can define this setup using a docker-compose.yml file:

version: '3'

services:
  keycloak:
    image: jboss/keycloak:11.0.0
    environment:
      DB_VENDOR: POSTGRES
      DB_ADDR: postgres
      DB_DATABASE: keycloak
      DB_USER: keycloak
      DB_PASSWORD: password
      KEYCLOAK_USER: test
      KEYCLOAK_PASSWORD: test
    ports:
      - "8080:8080"
    depends_on:
      - postgres

  postgres:
    image: postgres:11
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: password
    ports:
      - "5432:5432"

Run the setup with the following command:

docker-compose up -d

After the services are up, verify Keycloak’s functionality and the database connection through Keycloak’s Admin Console at http://localhost:8080(/auth).

Upgrading PostgreSQL Version

Upgrading your database is a critical step. We’ll guide you through upgrading to PostgreSQL version 14, showcasing the necessary changes in your docker-compose.yml file:

  postgres:
    image: postgres:14
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: password
    ports:
      - "5432:5432"

Verifying the Upgrade

After the upgrade, check the Docker logs for any errors or warnings:

docker-compose logs

Ensure there are no error messages related to database compatibility. Next, log in to the Keycloak Admin Console to verify that all entities and functionalities work as expected.

Important Considerations

  • Conduct these tests in an environment that closely mirrors your production setup. Using a copy of your production database for testing can provide more accurate results.
  • Always back up your data before attempting any upgrades in your production environment.
  • Monitor the application logs for any deprecated features or compatibility issues.

Conclusion

Upgrading components in your authentication infrastructure requires careful planning and testing. Docker-compose offers a convenient way to test different configurations, ensuring that upgrades do not disrupt your services. By following the steps outlined in this guide, you can confidently upgrade Keycloak and PostgreSQL, maintaining the security and reliability of your authentication system.