Deploy Keycloak Using Docker

Introduction

This tutorial will show you how to deploy your own Keycloak server.

Assumptions

This tutorial assumes that:

• You are deploying behind a reverse proxy that terminates the SSL/TLS connection.
• You have your own system for adding the TLS certificates to that reverse proxy such as using Let's Encrypt.

If you don't know how to deploy a reverse proxy, then you can do this manually, or through something like Nginx Proxy Manager, or Caddy. You can also use something like Traefik, but I believe that is actually the most complicated solution. Either way, there are a lot of solutions, which is why I don't prescribe one, and just assume you have one that you are comfortable configuring. I do provide the site configuration file for those that are using a manual Nginx proxy deployment though.

Steps

Docker Compose File

First, create a docker-compose.yaml file with the following content:

services:

  keycloak:
    image: quay.io/keycloak/keycloak:26.0
    restart: always
    command: start
    ports:
      - "80:8080"
    depends_on:
      - db
    environment:
      - KC_PROXY_ADDRESS_FORWARDING
      - KC_HOSTNAME_STRICT
      - KC_HOSTNAME
      - KC_PROXY
      - KC_HTTP_ENABLED=true
      - KC_DB=postgres
      - KC_DB_USERNAME=${DB_USER}
      - KC_DB_PASSWORD=${DB_PASSWORD}
      - KC_DB_URL_HOST=db
      - KC_DB_URL_PORT=5432
      - KC_DB_URL_DATABASE=${DB_NAME}
      - KEYCLOAK_ADMIN
      - KEYCLOAK_ADMIN_PASSWORD

  db:
    image: postgres:17.1-bullseye
    environment:
      - POSTGRES_USER=${DB_USER}
      - POSTGRES_DB=${DB_NAME}
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    volumes:
      - db-data:/var/lib/postgresql/data'

volumes:
  db-data:
    driver: local

KC_DB=postgres is telling keycloak that the type of database is Postgres (e.g. not MySQL etc). It is not the name of the database.

Create .env File

Now create a .env file within the same directory as the docker-compose.yaml file you created earlier.

COMPOSE_PROJECT_NAME=keycloak


KC_PROXY_ADDRESS_FORWARDING=true


# If set to true, this disables dynamically resolving the hostname 
# from request headers so that requests have to be made against 
# the KC_HOSTNAME you set
# https://www.keycloak.org/server/all-config?options-filter=all#category-hostname
KC_HOSTNAME_STRICT=true


# Specify your servers FQDN.
KC_HOSTNAME="https://keycloak.mydomain.com"


# Tell keycloak that the reverse proxy is terminating the TLS connection
# and passing HTTP traffic to keycloak.
# https://www.keycloak.org/server/reverseproxy
KC_PROXY=edge


# Specify HTTP to be enabled. This is assuming that keycloak will be 
# directed to through a reverse proxy that terminates the TLS connection
KC_HTTP_ENABLED=true


# Specify the database username. You shouldn't need to change this.
DB_USER=keycloak


# Specify the password for the database. Set this to something
# random/secure, just in case (database shouldn't be accessible 
# from the internet with the default setup).
DB_PASSWORD=""


# Sepcify the name for the database. 
# You shouldn't need to change this.
DB_NAME="keycloak"


# Specify the admin user credentials for Keycloak. You will use
# these details to login and configure the system.
KEYCLOAK_ADMIN="admin"
KEYCLOAK_ADMIN_PASSWORD=""

Be sure to fill in the KEYCLOAK_ADMIN_PASSWORD and DB_PASSWORD fields, as well as update the value for KC_HOSTNAME as appropriate to your FQDN.

Nginx Configuration

If your reverse proxy is deployed thorugh Nginx, then you can use the following site configuration file for your Keycloak server. Don't forget to generate and place the TLS certificates at the paths you specify for ssl_certificate and ssl_certificate_key.

server {
    listen 80;
    server_name keycloak.mydomain.com;
    return 301 https://$host$request_uri;
}


server {

    listen 443 ssl;
    ssl_certificate     /etc/nginx/ssl/my_mkcert_cert.pem;
    ssl_certificate_key /etc/nginx/ssl/my_mkcert_key.pem ;

    server_name         keycloak.mydomain.com;

    proxy_set_header X-Forwarded-For $proxy_protocol_addr; # To forward the original client's IP address 
    proxy_set_header X-Forwarded-Proto $scheme; # to forward the  original protocol (HTTP or HTTPS)
    proxy_set_header Host $host; # to forward the original host requested by the client

    location / {  
      proxy_pass http://keycloak.mydomain.com;
    }
}

Deploy!

Once you have all the configuration files in place, simply run:

docker compose up

... and your keycloak server should deploy. You should then be able to navigate to it in your browser, and use the username and password credentials you specified in the .env file to login for the first time and create the other user accounts.

References

• GitHub.com - Keycloak - How to get the reverse proxy / production settings to work
• keycloak.discourse.group - Keycloak in docker behind reverse proxy