keycloak-setup

A utility for:

• Creating a keycloak container image.
• Testing OpenID REST API using keycloak as the provider.

Pre-requisites:

• Podman or Docker.
• Python - Created with version 3.13.
• Poetry.

Run poetry install to set up the environment.

More documentation about running a keycloak instance can be found here.

Usage

Run poetry run python build.py -h or poetry run python build.py --help for script usage.

Application Container Image Features

Ports

Variable	Default Value	Description and Example
KC_HTTP_PORT	8080	The port Keycloak listens on for HTTP requests. This is the default port for non-secure connections. Example: To change the HTTP port to 9080, use -e KC_HTTP_PORT=9080.
KC_HTTPS_PORT	8443	The port Keycloak listens on for HTTPS requests. This is the default port for secure connections. Example: To change the HTTPS port to 9443, use -e KC_HTTPS_PORT=9443.

Environment variables

Variable	Default Value	Description and Example
KC_DB	dev-file	Specifies the database vendor to connect to. For an external PostgresSQL database, this must be set to postgres. Example: -e KC_DB=postgres
KC_DB_URL	None	The hostname or IP of the PostgresSQL database server. This is required for a production setup. Example: If your database container is named postgres-db, you would use -e KC_DB_URL_HOST=postgres-db.
KC_DB_USERNAME	None	The database user with permissions to create and manage the schema. Example: -e KC_DB_USERNAME=keycloak_user
KC_DB_PASSWORD	None	The password for the specified database user. This should be a secure value. Example: -e KC_DB_PASSWORD=my-secure-password
KC_HTTP_RELATIVE_PATH	None	Sets the base URL path for Keycloak when it's behind a reverse proxy. This ensures all redirects and resource links are correct. Example: -e KC_HTTP_RELATIVE_PATH=/auth makes the admin console accessible at https://yourdomain.com/auth/admin.
KC_HOSTNAME	None	The publicly accessible hostname for Keycloak. **This is required in production** for security. Example: -e KC_HOSTNAME=https://sso.yourdomain.com.
KC_HTTP_ENABLED	false	Enables HTTP listener. Must be set to true if your reverse proxy handles TLS and communicates with Keycloak over HTTP. Example: -e KC_HTTP_ENABLED=true.
KC_PROXY_HEADERS	None	Configures Keycloak to trust headers from a reverse proxy to correctly identify the original client's IP and protocol. Set to `forwarded` or `xforwarded`. Example: -e KC_PROXY_HEADERS=xforwarded.
KC_BOOTSTRAP_ADMIN_USERNAME	None	The username for the initial administrator. Required for the first-time startup of the container.
KC_BOOTSTRAP_ADMIN_PASSWORD	None	The password for the initial administrator. Required with KEYCLOAK_ADMIN.