|
<< Click to Display Table of Contents >> Raynet One > 2026.2 > Installation and Operations Guide > Raynet One On-Premises Installation and Operations Guide > Service Overview Keycloak Bootstrapper |
The Keycloak Bootstrapper is an initialization component that automatically configures the Keycloak identity provider during the first startup of the Raynet One on-premises deployment. It ensures that the required Keycloak realm, clients, and users are created before the main application services become available.
The Keycloak Bootstrapper runs as a short-lived init container using the harbor.raynetone.com/library/kc-realm-init Docker image. It executes once at deployment time and exits after completing the realm initialization process. The main application stack does not start until the bootstrapper finishes successfully.
This approach ensures a consistent, repeatable Keycloak configuration across all on-premises installations without requiring manual Keycloak administration.
During initialization, the Keycloak Bootstrapper performs the following tasks:
•Creates the Keycloak realm with the required settings for Raynet One.
•Registers OAuth 2.0 clients for the Backend, Frontend, and other application components.
•Configures roles and scopes required for authorization within the application.
•Creates the initial administrator user to allow first login after deployment.
The bootstrapper is built around two key internal components:
Initialization Binary
The realm initialization logic is handled by the binary located at:
tmp/kc_realm_init/kc_realm_init
This binary connects to the Keycloak Admin API and applies the realm configuration defined for the deployment. It reads its parameters from environment variables provided by the Docker Compose configuration.
Container Entrypoint
The container's startup behavior is controlled by the entrypoint script:
/usr/local/bin/kc-entrypoint
This script performs pre-flight checks, waits for the Keycloak service to become available, and then invokes the initialization binary. After successful completion, the container exits with a success status, allowing dependent services to start.
The Keycloak Bootstrapper follows this execution sequence:
1.The kc-realm-init container starts alongside the Keycloak service.
2.The kc-entrypoint script waits until the Keycloak Admin API is reachable.
3.The kc_realm_init binary applies the realm configuration to Keycloak.
4.The container exits successfully after completing initialization.
5.The Backend and Frontend services start only after this process completes.
Note:
If the bootstrapper fails (for example, because Keycloak did not become available in time or the Admin API returned an error), the deployment will not proceed. Check the container logs for diagnostic output before attempting a restart.
The bootstrapper is designed to be idempotent. If the realm already exists in Keycloak, re-running the bootstrapper will not overwrite existing configuration. This makes it safe to restart the container without risk of data loss.
Important:
Manual changes made to the Keycloak realm after initial setup are not managed by the bootstrapper. Consult Raynet Consulting before modifying realm settings to avoid configuration drift.
If the bootstrapper container exits with a non-zero status, perform the following diagnostic steps:
1.Review container logs to identify the error message reported by kc-entrypoint or kc_realm_init.
2.Verify that the Keycloak service is running and that its Admin API is reachable from within the Docker network.
3.Confirm environment variables used by the bootstrapper (Keycloak admin credentials, realm name, client IDs) are correctly set in the .env file.
4.Restart the container after resolving any identified issue. The bootstrapper is safe to run multiple times.
For further assistance, refer to the Troubleshooting section or contact Raynet Consulting.