Home > Developer Documentation Center > Server > Installation > Installing the Nuxeo Platform on Windows > Installing the Nuxeo Platform as a Windows Service
Server

Installing the Nuxeo Platform as a Windows Service

Updated: December 4, 2024

Installing Nuxeo as a Windows service is independent of Nuxeo Multiple solutions are available, here are some of them, given without any warranty.

Once a batch is installed as a service, it cannot be changed: you must first uninstall it, then edit and reinstall in order to change its content. So, it's generally a good idea to write a batch file wrapping calls to nuxeoctl.bat and install that NuxeoWrapper.bat as a service, which will be responsible of starting Nuxeo with the wanted user and environment parameters.

Prerequisites

In order to run as a service, you have to manage the directory rights for the super-user running the service. There are behavior changes depending on the Windows version.

Also, take care that network directories are usually not available when a service is executing. So, if you need to use some, you will have to mount them in the batch script before starting the Nuxeo Platform.

The database used by the Nuxeo Platform has to be installed as a service and started before the Nuxeo service.

Available Solutions

NSSM - Non-Sucking Service Manager (Experimental)

NSSM is a Windows service helper that makes it much more easy to launch any type of application as a service. What is more, it also handles failure, by relaunching applications whenever they exit prematurely. Here are the instructions to install Nuxeo as a Windows service using NSSM:

  1. Download NSSM from the official website or install it via Chocolatey, by typing: choco install nssm
  2. If NSSM was installed via Chocolatey, skip this step. Otherwise, add NSSM's location to PATH.
  3. Install Nuxeo as a service, by running on an elevated console or powershell: nssm install Nuxeo "<absolute-path-to-nuxeoctl.bat>" --gui false console

From now on, Nuxeo will start as a service whenever Windows starts. The console parameter allows the process to stay alive after the server starts, thus preventing NSSM from restarting it.

This seems to be the easiest solution so far, but thorough testing is yet to be performed.

YAJSW is a Java centric implementation of the Java Service Wrapper by tanuki (JSW). It aims at being mostly configuration compliant with the original. YAJSW is LGPL licensed. That solution seems to be the more flexible, robust and multi-OS compliant.

When using this solution it is important that Nuxeo installation path contains no space (typically NOT C:\Program Files\nuxeo). Otherwise the service wrapper will truncate the path after the space and the service will not start. It is recommended that Nuxeo is installed at the root of the volume (C:\nuxeo\ for instance).

Installing Nuxeo as a Windows Service Using YAJSW

  1. Download the latest stable version of YAJSW and unzip the archive.
  2. Set the system environment variable NUXEO_CONF to the location of your nuxeo.conf file, something like %NUXEO_HOME%\bin\nuxeo.conf.

  3. Start the Nuxeo Platform from the command line:

    nuxeoctl.bat --gui=false start

    Once the server is started, you'll get a message like below where XXXX is the process ID of the running Nuxeo application:

    Server started with process ID XXXX.

  4. Start a Command Prompt as an Administrator.

  5. Go to the %YAJSW_HOME%\bat folder.

  6. Execute the genConfigcommand with the process ID as parameter:

    genConfig.bat XXXX

    The configuration is written in the file %YAJSW_HOME%\conf\wrapper.conf.

    Wrapper Static Configuration Vs nuxeo.conf

    Once the wrapper configuration is generated, it is static. It means any further start of the Nuxeo service won't read nuxeo.conf to apply configuration changes.

    If you edit nuxeo.conf after having installed Nuxeo as a service, there are two possibilities:

    • Your changes are only about the configuration of Nuxeo: you only need to restart Nuxeo one time with its own launcher (step 3).
    • Your changes are about JVM options (changes in JAVA_OPTS variable: memory, debug ...): you'll have to start Nuxeo with its launcher and generate the new wrapper configuration (step 3 to 6).

    In both cases, you don't have to unregister the service and register it again: the wrapper will use the same configuration file (wrapper.conf).

  7. Stop the Nuxeo Platform.

    nuxeoctl.bat --gui=false stop

  8. Open the wrapper.conf file:

    • at the end of the file, add a new line among the additional java options to set the nuxeo.home environment property. In the example below, Nuxeo is installed in E:\Nuxeo and the new line is the 10th wrapper additional option:
    wrapper.java.additional.10 = -Dnuxeo.home=E:\\\\Applis\\\\Nuxeo
    • make sure the wrapper.console.title entry does not contain a colon (":") or the runConsole.bat execution will fail. In that case, remove the colon or set another title.

  9. Execute your wrapped application as a console application:

    runConsole.bat

  10. Check your application is accessible.

  11. Edit the file %YAJSW_HOME%\conf\wrapper.conf

    1. set your custom values for these parameters:

      # Name of the service
wrapper.ntservice.name=NuxeoPlatform
# Display name of the service
wrapper.ntservice.displayname=Nuxeo Platform
# Description of the service
wrapper.ntservice.description=Service to manage the Nuxeo Platform

wrapper.control = APPLICATION

    2. If set, remove or comment the following wrapper.on_exit parameters:

      #wrapper.on_exit.0=SHUTDOWN
#wrapper.on_exit.default=RESTART

      With the two above values set, the service would restart every time a server error occurs.

  12. Install the application as a service:

    installService.bat

    Your service is installed and you can run the Nuxeo Platform from its service ("Windows Computer Management > Services" on Windows 7).

JBoss Native Windows (aka JBossSVC, JBossService and JavaService)

Deprecated Nuxeo scripts managing install as a Windows service were previously used. They were based on JBoss Native Windows which is now not recommended because of a number of defects. However, it was relatively easy to use and provides a quick solution.

As an example, here is the content of jboss-native-2.0.4/bin/service.bat:

Nuxeo JBoss Service Script for Windows

@echo off
REM JBoss, the OpenSource webOS
REM
REM Distributable under LGPL license.
REM See terms of license at gnu.org.
REM
REM -------------------------------------------------------------------------
REM JBoss Service Script for Windows
REM -------------------------------------------------------------------------

@if not "%ECHO%" == "" echo %ECHO%
@if "%OS%" == "Windows_NT" setlocal
set DIRNAME=%CD%

REM
REM VERSION, VERSION_MAJOR and VERSION_MINOR are populated
REM during the build with ant filter.
REM
set SVCNAME=NuxeoEP
set SVCDISP=NuxeoEP
set SVCDESC=Nuxeo 5.3.0-GA / JBoss Application Server 4.2.3 GA / Platform: Windows 64
set NOPAUSE=Y

REM Suppress killing service on logoff event
set JAVA_OPTS=-Xrs

REM Figure out the running mode

if /I "%1" == "install"   goto cmdInstall
if /I "%1" == "uninstall" goto cmdUninstall
if /I "%1" == "start"     goto cmdStart
if /I "%1" == "stop"      goto cmdStop
if /I "%1" == "restart"   goto cmdRestart
if /I "%1" == "signal"    goto cmdSignal
echo Usage: service install^|uninstall^|start^|stop^|restart^|signal
goto cmdEnd

REM jbosssvc retun values
REM ERR_RET_USAGE           1
REM ERR_RET_VERSION         2
REM ERR_RET_INSTALL         3
REM ERR_RET_REMOVE          4
REM ERR_RET_PARAMS          5
REM ERR_RET_MODE            6

:errExplain
if errorlevel 1 echo Invalid command line parameters
if errorlevel 2 echo Failed installing %SVCDISP%
if errorlevel 4 echo Failed removing %SVCDISP%
if errorlevel 6 echo Unknown service mode for %SVCDISP%
goto cmdEnd

:cmdInstall
jbosssvc.exe -imwdc %SVCNAME% "%DIRNAME%" "%SVCDISP%" "%SVCDESC%" service.bat
if not errorlevel 0 goto errExplain
echo Service %SVCDISP% installed
goto cmdEnd

:cmdUninstall
jbosssvc.exe -u %SVCNAME%
if not errorlevel 0 goto errExplain
echo Service %SVCDISP% removed
goto cmdEnd

:cmdStart
REM Executed on service start
del .r.lock 2>&1 | findstr /C:"being used" > nul
if not errorlevel 1 (
  echo Could not continue. Locking file already in use.
  goto cmdEnd
)
echo Y > .r.lock
jbosssvc.exe -p 1 "Starting %SVCDISP%" > run.log
call run.bat -b 0.0.0.0 < .r.lock >> run.log 2>&1
jbosssvc.exe -p 1 "Shutdown %SVCDISP% service" >> run.log
del .r.lock
goto cmdEnd

:cmdStop
REM Executed on service stop
echo Y > .s.lock
jbosssvc.exe -p 1 "Shutting down %SVCDISP%" > shutdown.log
call shutdown -S < .s.lock >> shutdown.log 2>&1
jbosssvc.exe -p 1 "Shutdown %SVCDISP% service" >> shutdown.log
del .s.lock
goto cmdEnd

:cmdRestart
REM Executed manually from command line
REM Note: We can only stop and start
echo Y > .s.lock
jbosssvc.exe -p 1 "Shutting down %SVCDISP%" >> shutdown.log
call shutdown -S < .s.lock >> shutdown.log 2>&1
del .s.lock
:waitRun
REM Delete lock file
del .r.lock > nul 2>&1
REM Wait one second if lock file exist
jbosssvc.exe -s 1
if exist ".r.lock" goto waitRun
echo Y > .r.lock
jbosssvc.exe -p 1 "Restarting %SVCDISP%" >> run.log
call run.bat < .r.lock >> run.log 2>&1
jbosssvc.exe -p 1 "Shutdown %SVCDISP% service" >> run.log
del .r.lock
goto cmdEnd

:cmdSignal
REM Send signal to the service.
REM Requires jbosssch.dll to be loaded in JVM
@if not ""%2"" == """" goto execSignal
echo Missing signal parameter.
echo Usage: service signal [0...9]
goto cmdEnd
:execSignal
jbosssvc.exe -k%2 %SVCNAME%
goto cmdEnd

:cmdEnd

Other implementations were available from JBoss.

They were licensed under LGPL and so redistributable but there are not fully satisfying.

JavaServiceWrapper by Tanuki

Tanuki's library provides multiple methods for integrating a software as a service on various OS, the easier is to use the WrapperSimpleApp helper class to launch the application: see the example of JBoss installed as a Windows service. It requires to unzip the downloaded wrapper file, configure a wrapper.conf file pointing to %NUXEO_HOME%\bin\nuxeoctl.bat, then write a wrapper.bat file for managing test/install/uninstall:

JavaServiceWrapper usage

REM Test:
wrapper.exe -c %NUXEO_HOME%\wrapper\wrapper.conf

REM Install:
wrapper.exe -i %NUXEO_HOME%\wrapper\wrapper.conf

REM Uninstall:
wrapper.exe -r %NUXEO_HOME%\wrapper\wrapper.conf

This solution is known to work well but is sadly not redistributable for us because of its GPL/Commercial license.

Tomcat Service Install/Uninstall Script (deprecated)

Previous versions of the Tomcat distribution of Nuxeo came with a service.bat script in the bin directory that could be adapted to install Nuxeo as a Windows service.

.NET InstallUtil (deprecated)

.NET framework provides an InstallUtil.exe tool for installing/uninstalling services.

InstallUtil usage

REM Install
InstallUtil /i %NUXEO_HOME\bin\service.bat

REM Uninstall
InstallUtil /u %NUXEO_HOME\bin\service.bat

There are some disadvantages such as failures in case of multiple frameworks installed and frontward/backward incompatibilities.

You may want to have a look at http://msdn2.microsoft.com/en-US/library/system.configuration.install.managedinstallerclass.aspx for managing that programmatically.

Next Steps
Getting Familiar with the Nuxeo Platform