copy "path\to\prunsrv.exe" "%KEYCLOAK_HOME%\bin\prunsrv.exe"This guide explains how to install and run Keycloak as a Windows service using Apache Commons Daemon. The service runs kc.bat in "exe" mode so behavior matches running kc.bat start manually. The service runs in "exe" mode, where Procrun executes kc.bat start as an external process. Environment variables, such as KC_*, along with conf/keycloak.conf, are respected. The kc.bat script handles augmentation and build logic, ensuring the service behaves exactly like a manual start.
To run Keycloak as a Windows service, you need the Apache Commons Daemon Procrun binary (prunsrv.exe). Download it for your platform: https://downloads.apache.org/commons/daemon/binaries/windows/
Then place prunsrv.exe into the Keycloak bin folder.
copy "path\to\prunsrv.exe" "%KEYCLOAK_HOME%\bin\prunsrv.exe"Use the amd64 binary for 64-bit and x86 for 32-bit systems.
Pre-building is optional. If you do not pre-build, Keycloak will build automatically on first start, which takes longer.
bin/kc.bat build --db=postgresKeycloak includes a tools windows-service subcommand to simplify service installation and uninstallation.
bin\kc.bat tools windows-service install --helpbin\kc.bat tools windows-service uninstall --helpInstall a basic service (runs as Local System by default):
bin\kc.bat tools windows-service install --name keycloakManual startup and longer stop timeout:
bin\kc.bat tools windows-service install --startup=manual --stop-timeout=60Delayed auto-start:
bin\kc.bat tools windows-service install --startup=delayedCustom display name:
bin\kc.bat tools windows-service install --name=my-keycloak --display-name="My Keycloak Server"Use --depends-on to ensure required Windows services start before Keycloak (for example, a local database). By default Apache Commons Daemon may add Tcpip and Afd network dependencies.
bin\kc.bat tools windows-service install --depends-on="postgresql-x64-15;Tcpip;Afd"The default is to run the service as the Local System account - --service-user and --service-password can be omitted (recommended). To run as a specific user, the account must have the "Log on as a service" right.
bin\kc.bat tools windows-service install --service-user="DOMAIN\Username" --service-password="password"You can supply the service password securely via an environment variable, which is recommended:
set KC_SERVICE_PASSWORD=s3cret
bin\kc.bat tools windows-service install --service-user="DOMAIN\Username"Start the service:
net start keycloakStop the service:
net stop keycloakUninstall the service:
bin\kc.bat tools windows-service uninstall --name keycloakCheck status using the Windows Services console (services.msc).
When Keycloak runs as a service, it is recommended to enable file logging - see Configuring logging.
The service wrapper logs (e.g. commons-daemon.YYYY-MM-DD.log) respects the log-path option value during service creation.
To change runtime configuration:
Stop the service: net stop keycloak.
Update environment variables or conf/keycloak.conf.
Optionally re-run build: bin\kc.bat build [new-options].
Start the service: net start keycloak.
Ensure the service runs as Local System (default) or that the specified account has "Log on as a service".
Windows Services run in a separate session (usually as the LocalSystem account) and do not inherit the environment variables of the user who created the service. Define the required KC_* environment variables as system-wide environment variables, so they are available to the service.
When you create the service, the following Apache Commons Daemon Procrun settings are applied:
StartMode: exe (runs kc.bat as an external process)
StartImage: <KEYCLOAK_HOME>\bin\kc.bat
StartParams: start
StopMode: exe
StopImage: <KEYCLOAK_HOME>\bin\kc.bat
StopParams: stop
StopTimeout: configurable (default: 30 seconds)
Service configuration is stored in the Windows Registry under:
HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Apache Software Foundation\ProcRun 2.0\<ServiceName>