Home > Software > How to Deploy Keycloak & Postgres with Docker Compose

How to Deploy Keycloak & Postgres with Docker Compose

Anastasios Antoniadis

Discover how to effortlessly set up Keycloak with PostgreSQL for secure authentication in your applications using Docker Compose. This ultimate guide provides step-by-step instructions, best practices, and tips to streamline your authentication system.

Docker (1)

In application development, a secure and efficient user authentication system is crucial. Fortunately, Docker Compose, Keycloak, and PostgreSQL can work together to provide a powerful solution for managing authentication services with ease and flexibility. This guide is designed to help you integrate Keycloak, an open-source Identity and Access Management solution, with PostgreSQL using Docker Compose. Doing so gives you a robust authentication system for your applications.

The importance of secure authentication cannot be overstated in today’s digital age, where data breaches and unauthorized access are ever-looming threats. By the end of this article, you will have a comprehensive understanding of setting up Keycloak with PostgreSQL in a Dockerized environment, ensuring your applications are fortified with a secure, scalable, and manageable authentication system.

Understanding the Components

Docker Compose

Docker Compose is a tool for defining and running multi-container Docker applications. With a simple YAML file, you can configure your application’s services, networks, and volumes, and then, with a single command, you can create and start all those services. It simplifies application deployment and scalability, making it indispensable for developers.


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 and offers features like Single Sign-On (SSO), social login, and 2FA. Keycloak stands out for its flexibility and ease of integration into various platforms.


PostgreSQL is a powerful, open-source object-relational database system known for its reliability, feature robustness, and performance. When used with Keycloak, it is an excellent choice for storing user data and handling authentication requests.


Before diving into the setup process, ensure you have Docker and Docker Compose installed on your machine. A basic understanding of containerization, Docker networking, and authentication mechanisms will also be beneficial.

Setting Up the Environment

The heart of this setup is the Docker Compose file, which orchestrates the Keycloak and PostgreSQL services. Here’s a basic structure of what this file will look like:

version: '3'
    image: quay.io/keycloak/keycloak:latest
      - "8080:8080"
      - KEYCLOAK_ADMIN=admin
      - KC_HOSTNAME_ADMIN=localhost
      - KC_PROXY=edge
      - KC_HOSTNAME=localhost
      - KC_HEALTH_ENABLED=true
      - KC_DB=postgres
      - KC_DB_PASSWORD=password
      - KC_DB_SCHEMA=public
      - KC_DB_USERNAME=keycloak
      - KC_DB_URL_HOST=postgres
      - KC_DB_URL_DATABASE=keycloak
      - postgres
      - start
      - ./auth/import:/opt/keycloak/data/import

    image: postgres
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: password
      - postgres_data:/var/lib/postgresql/data

      driver: local

This configuration outlines two main services: keycloak and postgres. The Keycloak service is configured to connect to the PostgreSQL database using environment variables. The depends_on attribute ensures that the PostgreSQL service is started before Keycloak.

Running Keycloak with PostgreSQL Using Docker Compose

To launch the services, navigate to the directory containing your docker-compose.yml file and execute the following command:

docker compose up -d

This command starts the services in detached mode. You can verify the setup by accessing the Keycloak admin console through http://localhost:8080.

Configuring Keycloak for First Use

Once your Keycloak service is running, you can access the admin console to start configuring realms, clients, and users.

Accessing the Keycloak Admin Console

  1. Open a web browser and navigate to http://localhost:8080/auth.
  2. Log in to the Admin Console using the default credentials (admin for both username and password) provided during the first startup.
  3. After login, you’ll be prompted to change the admin password for security reasons.

Creating Realms, Clients, and Users

  • Realms: A realm in Keycloak is a space that manages a set of users, credentials, roles, and groups. To create a new realm:
    1. Click on the dropdown in the top-left corner where the current realm name is displayed.
    2. Select “Add realm” and fill in the form with your realm’s name.
  • Clients: Clients are entities that can request Keycloak to authenticate a user. For example, your application.
    1. Within the realm, select “Clients” from the left menu.
    2. Click “Create” and enter the required information, such as Client ID and Root URL.
  • Users: Users are individuals who can log in to your application.
    1. Select “Users” from the left menu.
    2. Click “Add user” and fill in the user details. After creating a user, you can set up their credentials under the “Credentials” tab.

Integrating Keycloak with Your Application

To secure your application with Keycloak, you’ll need to use Keycloak adapters or libraries corresponding to the programming language or framework your application is built with.

Overview of Client Adapters and Protocols

Keycloak supports authentication protocols, including OpenID Connect (OIDC) and SAML. You can choose the appropriate protocol and use the corresponding Keycloak adapter depending on your application’s needs.

Example of Integrating with a Sample Application

Assuming your application is a simple web application using OIDC for authentication:

  1. Configuration: Use the Keycloak OIDC JSON adapter configuration file (keycloak.json) provided by Keycloak during the client creation process. This file includes details such as the client ID, secret, and Keycloak server URL.
  2. Securing Endpoints: Implement security constraints in your application to protect resources. For example, in a Java application, you can configure security constraints in the web.xml file or through annotations.
  3. Accessing User Information: After successful authentication, your application can retrieve the user’s profile, roles, and other details from Keycloak.

Best Practices and Troubleshooting

Security Considerations

  • SSL/TLS: Always use HTTPS to secure communication between your application and Keycloak. You can use self-signed certificates for local development, but ensure to use valid certificates in production.
  • Secrets Management: Securely manage secrets such as client secrets and passwords. Avoid hardcoding them in your application.

Performance Optimization Tips

  • Caching: Enable caching in Keycloak to reduce database load and improve authentication response times.
  • Scaling: Utilize Docker Compose’s scaling capabilities to handle high availability and load balancing for Keycloak and PostgreSQL services.

Common Issues and Solutions

  • Connection Issues: Ensure your Docker containers can communicate with each other. Check Docker network configurations and service dependencies.
  • Configuration Errors: Verify your docker-compose.yml and Keycloak configuration settings. Ensure environment variables and volume mounts are correctly defined.


Integrating Keycloak with PostgreSQL using Docker Compose offers a robust solution for managing authentication and authorization in your applications. You can ensure secure and efficient user management by following the steps outlined in this guide, from setting up the environment to configuring Keycloak and integrating it with your application. As you become more familiar with Keycloak’s features and Docker Compose’s capabilities, you’ll discover even more ways to optimize and secure your application’s authentication system.


  1. How can I update Keycloak without downtime?
    • Use Docker Compose to pull the latest Keycloak image and restart the service. Implement a zero-downtime deployment strategy using Docker Compose’s support for rolling updates.
  2. How do I manage backups of the PostgreSQL database?
    • Utilize Docker volumes for PostgreSQL data and implement regular backup procedures using database tools or scripts.
  3. Tips for scaling Keycloak and PostgreSQL services with Docker Compose?
    • For Keycloak, scale horizontally by increasing the number of instances. For PostgreSQL, consider using replication for scaling reads and ensuring high availability.

By embracing Docker Compose, Keycloak, and PostgreSQL, you’re setting a foundation for secure, scalable, and manageable application authentication services. To further enhance your setup, continue exploring Keycloak’s extensive documentation and the Docker community for advanced features and best practices.

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