Install as a Service on Windows

OrientDB is a Java server application. As most server applications, they have to perform several tasks, before being able to shut down the Virtual Machine process, hence they need a portable way to be notified of the imminent Virtual Machine shutdown. At the moment, the only way to properly shut down an OrientDB server instance (not embedded) is to execute the shutdown.bat (or shutdown.sh) script shipped with the OrientDB distribution, but it’s up to the user to take care of this. This implies that the server instance isn’t stopped correctly, when the computer on which it is deployed, is shut down without executing the above script.

Apache Commons Daemon

Apache Commons Daemon is a set of applications and API enabling Java server application to run as native non interactive server applications under Unix and Windows. In Unix, server applications running in the background are called daemons and are controlled by the operating system with a set of specified signals. Under Windows, such programs are called services and are controlled by appropriate calls to specific functions defined in the application binary. Although the ways of dealing with running daemons or services are different, in both cases the operating system can notify a server application of its imminent shutdown, and the underlying application has the ability to perform certain tasks, before its process of execution is destroyed. Wrapping OrientDB as a Unix daemon or as a Windows service enables the management of this server application lifecycle through the mechanisms provided natively by both Unix and Windows operating systems.

Installation

This tutorial is focused on Windows, so you have to download procrun. Procrun is a set of applications, which allow Windows users to wrap (mostly) Java applications (e.g. Tomcat) as a Windows service. The service can be set to automatically start, when the machine boots and will continue to run with no user logged onto the machine.

  1. Point you browser to the Apache Commons Daemon download page.
  2. Click on Browse native binaries download area…: you will see the index commons/daemon/binaries/ (even if the title in the page reports Index of dist/commons).
  3. Click on windows. Now you can see the index of commons/daemon/binaries/windows.
  4. Click on commons-daemon-1.0.7-bin-windows.zip. The download starts.
  5. Unzip the file in a directory of your choice. The content of the archive is depicted below:
  1. commons-daemon-1.0.7-bin-windows
  2. |
  3. \---amd64
  4.     |
  5.     \---prunsrv.exe
  6. |
  7. \---ia64
  8.     |
  9.     \---prunsrv.exe
  10. |
  11. \---LICENCE.txt
  12. |
  13. \---NOTICE.txt
  14. |
  15. \---prunmgr.exe
  16. |
  17. \---prunsrv.exe
  18. |
  19. \---RELEASE-NOTES.txt

prunmgr is a GUI application for monitoring and configuring Windows services wrapped with procrun. prunsrv is a service application for running applications as services. It can convert any application (not just Java applications) to run as a service. The directory amd64 contains a version of prunsrv for x86-64 machines while the directory ia64 contains a version of prunsrv for Itanium 64 machines.

Once you downloaded the applications, you have to put them in a folder under the OrientDB installation folder.

  1. Go to the OrientDB folder, in the following referred as %ORIENTDB_HOME%
  2. Create a new directory and name it service
  3. Copy there the appropriate versions of prunsrv and prunmgr according to the architecture of your machine.

Configuration

In this section, we will show how to wrap OrientDB as a Windows Service. In order to wrap OrientDB as a service, you have to execute a short script that uses the prunsrv application to configure a Windows Service.

Before defining the Windows Service, you have to rename prunsrv and prunmgr according to the name of the service. Both applications require the name of the service to manage and monitor as parameter but you can avoid it by naming them with the name of the service. In this case, rename them respectively OrientDBGraph and OrientDBGraphw as OrientDBGraph is the name of the service that you are going to configure with the script below. If you want to use a difference service name, you have to rename both application respectively myservicename and myservicenamew (for example, if you are wrapping OrientDB and the name of the service is OrientDB, you could rename prunsrv as OrientDB and prunmgr as OrientDBw). After that, create the file %ORIENTDB_HOME%\service\installService.bat with the content depicted below:

  1. :: OrientDB Windows Service Installation
  2. @echo off
  3. rem Remove surrounding quotes from the first parameter
  4. set str=%~1
  5. rem Check JVM DLL location parameter
  6. if "%str%" == "" goto missingJVM
  7. set JVM_DLL=%str%
  8. rem Remove surrounding quotes from the second parameter
  9. set str=%~2
  10. rem Check OrientDB Home location parameter
  11. if "%str%" == "" goto missingOrientDBHome
  12. set ORIENTDB_HOME=%str%
  14. set CONFIG_FILE=%ORIENTDB_HOME%/config/orientdb-server-config.xml
  15. set LOG_FILE=%ORIENTDB_HOME%/config/orientdb-server-log.properties
  16. set LOG_CONSOLE_LEVEL=info
  17. set LOG_FILE_LEVEL=fine
  18. set WWW_PATH=%ORIENTDB_HOME%/www
  19. set ORIENTDB_ENCODING=UTF8
  20. set ORIENTDB_SETTINGS=-Dprofiler.enabled=true -Dcache.level1.enabled=false -Dcache.level2.strategy=1
  21. set JAVA_OPTS_SCRIPT=-XX:+HeapDumpOnOutOfMemoryError
  23. rem Install service
  24. OrientDBGraphX.X.X.exe //IS --DisplayName="OrientDB GraphEd X.X.X" ^
  25. --Description="OrientDB Graph Edition, aka GraphEd, contains OrientDB server integrated with the latest release of the TinkerPop Open Source technology stack supporting property graph data model." ^
  26. --StartClass=com.orientechnologies.orient.server.OServerMain --StopClass=com.orientechnologies.orient.server.OServerShutdownMain ^
  27. --Classpath="%ORIENTDB_HOME%\lib\*" --JvmOptions "-Dfile.Encoding=%ORIENTDB_ENCODING%;-Djava.util.logging.config.file="%LOG_FILE%";-Dorientdb.config.file="%CONFIG_FILE%";-Dorientdb.www.path="%WWW_PATH%";-Dlog.console.level=%LOG_CONSOLE_LEVEL%;-Dlog.file.level=%LOG_FILE_LEVEL%;-Dorientdb.build.number="@BUILD@";-DORIENTDB_HOME=%ORIENTDB_HOME%" ^
  28. --StartMode=jvm --StartPath="%ORIENTDB_HOME%\bin" --StopMode=jvm --StopPath="%ORIENTDB_HOME%\bin" --Jvm="%JVM_DLL%" --LogPath="%ORIENTDB_HOME%\log" --Startup=auto
  30. EXIT /B
  32. :missingJVM
  33. echo Insert the JVM DLL location
  34. goto printUsage
  36. :missingOrientDBHome
  37. echo Insert the OrientDB Home
  38. goto printUsage
  40. :printUsage
  41. echo usage:
  42. echo     installService JVM_DLL_location OrientDB_Home
  43. EXIT /B

The script requires two input parameters:

  1. The location of jvm.dll, for example C:\Program Files\Java\jdk1.6.0_26\jre\bin\server\jvm.dll
  2. The location of the OrientDB installation folder, for example D:\orientdb-graphed-1.0rc5

The service is actually installed when executing OrientDBGraph.exe (originally prunsrv) with the appropriate set of command line arguments and parameters. The command line argument //IS states that the execution of that application will result in a service installation. Below there is the table with the command line parameters used in the above script.

Parameter nameDescriptionSource
—DisplayNameThe name displayed in the Windows Services Management ConsoleCustom
—DescriptionThe description displayed in the Windows Services Management ConsoleCustom
—StartClassClass that contains the startup method (= the method to be called to start the application). The default method to be called is the main methodThe class invoked in the /bin/server.bat script
—StopClassClass that will be used when receiving a Stop service signal. The default method to be called is the main methodThe class invoked in the /bin/shutdown.bat script
—ClasspathSet the Java classpathThe value of the -cp parameter specified in the %ORIENTDB_HOME%\bin\server.bat script
—JvmOptionsList of options to be passed to the JVM separated using either # or ; charactersThe list of options in the form of -D or -X specified in the %ORIENTDB_HOME%\bin\server.bat script and the definition of the ORIENTDBHOME system property
—StartModeSpecify how to start the process. In this case, it will start Java in-process and not as a separate imageBased on Apache Tomcat configuration
—StartPathWorking path for the StartClass%ORIENTDBHOME%\bin
—StopModeThe same as —StartModeBased on Apache Tomcat configuration
—StopPathWorking path for the StopClass%ORIENTDB_HOME%\bin
—JvmWhich jvm.dll to use: the default one or the one located in the specified full pathThe first input parameter of this script. Ensure that you insert the location of the Java HotSpot Server VM as a full path. We will use the server version for both start and stop.
—LogPathPath used by prunsrv for loggingThe default location of the Apache Commons Daemon log
—StartupStates if the service should start at machine start up or manuallyauto
For a complete reference to all available parameters and arguments for prunsrv and prunmgr, visit the Procrun page.

In order to install the service:

  1. Open the Windows command shell
  2. Go to %ORIENTDB_HOME%\service, for example typing in the shell > cd D:\orientdb-graphed-1.0rc5\service
  3. Execute the installService.bat specifying the jvm.dll location and the OrientDB Home as full paths, for example typing in the shell > installService.bat “C:\Program Files\Java\jdk1.6.0_26\jre\bin\server\jvm.dll” D:\orientdb-graphed-1.0rc5
  4. Open the Windows Services Management Console - from the taskbar, click on Start, Control Panel, Administrative Tools and then Service - and check the existance of a service with the same name specified as value of the —DisplayName parameter (in this case OrientDB GraphEd 1.0rc5). You can also use %ORIENTDB_HOME%\service\OrientDBGraphw.exe to manage and monitor the OrientDBGraph service.

Other resources

To learn more about how to install OrientDB on specific environment please follow the guide below: