jeffersonlab/keycloak repository overview

⁠keycloak

Configurable Keycloak⁠ Docker image and bash setup scripts.

• Overview⁠
• Quick Start with Compose⁠
• Configure⁠
• Release⁠

⁠Overview

This project provides a docker image which extends the production-oriented keycloak⁠ and adds features for development and testing. The Jefferson Lab image sets up a Docker healthcheck and Docker entrypoint, installs client tools (see kc-lib.sh⁠), and adds some default configuration for the Jefferson Lab environment. The entrypoint integrates with the healthcheck such that the container is "healthy" only when keycloak is both running and configured. Configuration is supported via environment variables and a conventional directory named /container-entrypoint-initdb.d of bash scripts that can be overwritten by mounting a volume.

• 1.x version based on Keycloak 20.x
• 2.x version based on Keycloak 26.x

⁠Quick Start with Compose

1. Grab project

git clone https://github.com/JeffersonLab/keycloak
cd keycloak

1. Launch Compose⁠

docker compose up

1. Navigate to admin console

http://localhost:8081/auth

Note: Login with username admin and password admin

⁠Configure

Mount a volume at /container-entrypoint-initdb.d containing bash scripts to run, ordered by name ascending. See example⁠. Mount a subdirectory (e.g. 99-conf.d) or individual files in this location to keep default config as overriding the /container-entrypoint-initdb.d/ will overwrite the default configuration.

Environment variables:

Notes on Default Configuration:

• Additional environment variables are set in 00_config.env⁠. These can only be overridden by replacing this file or providing an additional env file to be sourced after.
• Each client will use the same client_secret: yHi6W2raPmLvPXoxqMA7VWbLAA2WN0eB
• Four users are created all with the password password: jadams, jdoe, jsmith, and tbrown
• All users have ${KC_RESOURCE}-user role. jdoe and tbrown have ${KC_RESOURCE}-admin role
• Client has KC_UPDATE_CLIENT_ROLES_MAPPER unset by default

Notes on Setup and Persistence:

• The setup scripts run once, after Keycloak first starts, and then the entrypoint writes a setup-complete marker file. The container is healthy only once the marker exists and Keycloak responds at KC_BACKEND_URL.
• With the default embedded (dev-file) database the marker is written to /opt/keycloak/data/setup-complete, next to the database. If you mount a volume at /opt/keycloak/data, a recreated container keeps its realm and skips setup. Without a volume, a new container starts fresh and runs setup again.
• With an external database (e.g. KC_DB=oracle) the marker is written to /opt/keycloak/setup-complete, in the container itself, so a recreated container runs the setup scripts again against the existing database. Set KC_SKIP_DEFAULT_SETUP=true (or make your own scripts idempotent) if the database outlives the container.
• The entrypoint runs until Keycloak exits and then exits with Keycloak's status, so Docker restart policies (e.g. restart: unless-stopped) apply if Keycloak stops. docker stop is passed on to Keycloak for a clean shutdown.

⁠Release

1. Bump the version number in the VERSION file and commit and push to GitHub (using Semantic Versioning⁠).
2. The CD⁠ GitHub Action should run automatically invoking:
   • The Create release⁠ GitHub Action to tag the source and create release notes summarizing any pull requests. Edit the release notes to add any missing details.
   • The Publish docker image⁠ GitHub Action to create a new demo Docker image.