Running CrateDB as a service on Windows

Tutorials
,
1

When following the self-hosted CrateDB installation method for Windows, CrateDB can be started with .\bin\crate.bat. This implies that the process is attached to the current command line session and doesn’t run in the background as a service. In this article, we want to explore a possible way to run CrateDB on Windows as a background service.

To enable CrateDB to respond properly to a service’s lifecycle events (such as start and stop), we will make use of Apache Commons Daemon.

Please note that Windows is one of the supported installation platforms. However, support is limited to testing and development purposes. For production purposes, please contact us so we can work with you on a solution.

Prerequisites

  • Download the Commons Daemon binary and unpack it. In this example, we installed it to C:\commons-daemon.
  • Download the latest CrateDB Windows ZIP archive and unpack it. In this example, we installed it to C:\Users\crate\crate-5.7.0.

Service setup

To start or stop the CrateDB application, the embedded Java Development Kit needs to call the main or close method of the class io.crate.bootstrap.CrateDB.

Additionally, the Java Virtual Machine (JVM) needs to be configured by passing certain options (--JvmOptions). When starting CrateDB interactively with .\bin\crate.bat, the JVM options are generated by that script, but not made directly visible.

To obtain the JVM options, you may temporarily comment out the statement @ECHO OFF in bin\crate.bat. On the next start of CrateDB, you will see an output similar to the one below on your command line:

"C:\Users\crate\crate-5.7.0\jdk\bin\java"  -Xms256m -Xmx1g -Xss256k -XX:+UseG1GC -XX:G1ReservePercent=25 -XX:InitiatingHeapOccupancyPercent=30 -Xlog:gc*,gc+age=trace,safepoint:file="C:\Users\crate\crate-5.7.0\logs\gc.log":utctime,pid,tags:filecount=16,filesize=64m -XX:+DisableExplicitGC -Djna.nosys=true -Dfile.encoding=UTF-8 -Dlog4j.shutdownHookEnabled=false -Dlog4j2.disable.jmx=true -Dlog4j.skipJansi=true -Dio.netty.recycler.maxCapacityPerThread=0 -XX:+HeapDumpOnOutOfMemoryError  -cp "C:\Users\crate\crate-5.7.0/lib/*" "io.crate.bootstrap.CrateDB" -Cpath.home="C:\Users\crate\crate-5.7.0" !newparams!

That output includes all the information we need for the service definition. However, names differ in the service definition and we need to map them:

  • -Xms: Initial/minimum heap size, becomes --JvmMs
  • -Xmx: Maximum heap size, becomes --JvmMx, but must be specified in megabytes
  • -Xss: Java stack size, becomes --JvmSs
  • -cp: The Java classpath, becomes --Classpath
  • All remaining options: Become --JvmOptions. The parameter -Cpath.home is renamed to -Des.path.home. As a separator between options, either # or ; must be used instead of a space.

Combining all of the above, the service can finally be created through a command line with administrative privileges:

cd C:\commons-daemon\amd64
.\prunsrv.exe //IS//CrateDB `
    --DisplayName "CrateDB" `
    --JavaHome "C:\Users\crate\crate-5.7.0\jdk" `
    --Jvm "C:\Users\crate\crate-5.7.0\jdk\bin\server\jvm.dll" `
    --JvmOptions "-Des.path.home=C:\Users\crate\crate-5.7.0#-XX:+UseG1GC#-XX:G1ReservePercent=25#-XX:InitiatingHeapOccupancyPercent=30#-Xlog:gc*,gc+age=trace,safepoint:file=C:\Users\crate\crate-5.7.0\logs\gc.log:utctime,pid,tags:filecount=16,filesize=64m#-XX:+DisableExplicitGC#-Djna.nosys=true#-Dfile.encoding=UTF-8#-Dlog4j.shutdownHookEnabled=false#-Dlog4j2.disable.jmx=true#-Dlog4j.skipJansi=true#-Dio.netty.recycler.maxCapacityPerThread=0#-XX:+HeapDumpOnOutOfMemoryError" `
    --Classpath "C:\Users\crate\crate-5.7.0/lib/*" `
    --JvmMs 256 `
    --JvmMx 1024 `
    --JvmSs 256 `
    --StopClass "io.crate.bootstrap.CrateDB" `
    --StopMethod "close" `
    --StopMode "jvm" `
    --StartPath "C:\Users\crate\crate-5.7.0" `
    --StartClass "io.crate.bootstrap.CrateDB" `
    --StartMethod "main" `
    --StartMode "jvm" `
    --LogPath "C:\commons-daemon" `
    --LogPrefix "commons-daemon" `
    --LogLevel "Debug" `
    --StdError "C:\Users\crate\CrateDBStdErr.log" `
    --StdOutput "C:\Users\crate\CrateDBStdOut.log" `
    --PidFile "CrateDB.pid"

Please refer to the Procrun documentation for a full list of available parameters. Once created, the service can be operated by the standard Windows Services Manager.

Wrap-up

Using Apache Commons Daemon, we could turn CrateDB into a background service on Windows.

In a default CrateDB installation, Java properties are encapsulated in crate.bat and do not leak into other components, like services. As the presented service definition breaks this isolation, it is important to keep it up to date with newer CrateDB versions. In release notes or similar documentation, we will not explicitly remind you to do so, it remains in your own responsibility to keep the service definition aligned.

2 Likes