Preloader image

Windows Service

It is possible to configure TomEE to run as Windows service, and batch files are provided in the bin folder to accomplish this. The key batch file is service.bat, and this provides commands to install and remove the service. Additionally two helper files are provided to simplify the installation and create a basic service setup.

  • service.install.as.admin.bat

  • service.remove.as.admin.bat

Installation

These instructions assume you have already downloaded a TomEE zip file and extracted it to the desired location on the file system, and that you have a suitable Java installation on your machine.

Start by opening a Command Prompt as an Administrator user.

Ensure you have JAVA_HOME set to the JDK you wish to use for the service. You can check this by running set JAVA_HOME.

Run service install. Optionally you can pass a service name, and credentials for a service user.

service install [/service-user <user>] [/service-password <password>] [service name]

For example:

    C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT\bin>service install TomEE-DEV
    Installing the service 'TomEE-DEV' ...
    Using CATALINA_HOME:    "C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT"
    Using CATALINA_BASE:    "C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT"
    Using JAVA_HOME:        "C:\Java\jdk-11.0.4+11
    Using JRE_HOME:         "C:\Java\jdk-11.0.4+11"
    Using JVM:              "C:\Java\jdk-11.0.4+11"\bin\server\jvm.dll"
    Using Service User:     ""
    Installed, will now configure TomEE
    The service 'TomEE-DEV' has been installed.

    C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT\bin>

Removal

Removal is similar to installation. First, ensure the service is stopped. In an administrator Command Prompt, run:

service remove [service name]

For example:

    C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT\bin>service remove TomEE-DEV
    The service 'TomEE-DEV' has been removed

    C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT\bin>

Service Accounts

Ny default, the service is installed to run at the user NT-Authority\Local Service, which is a very restricted account. If you wish to use LocalSystem, which has more privileges, use:

service install /service-user LocalSystem [service name]

For example:

C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT\bin>service install /service-user LocalSystem TomEE-DEV
Installing the service 'TomEE-DEV' ...
Using CATALINA_HOME:    "C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT"
Using CATALINA_BASE:    "C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT"
Using JAVA_HOME:        "C:\Java\jdk-11.0.4+11"
Using JRE_HOME:         "C:\Java\jdk-11.0.4+11"
Using JVM:              "C:\Java\jdk-11.0.4+11"\bin\server\jvm.dll"
Using Service User:     "LocalSystem"
Installed, will now configure TomEE
The service 'TomEE-DEV' has been installed.

C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT\bin>

Alternatively, you may have a specific local or domain user you wish to use to run the service. You can specify the username and password for the service user with the /service-user and /service-password parameters.

Making Changes

Once the service is installed, it is possible to make changes either using the Windows Service Control Manager (start, stop, change user) or by running the TomEE.exe executable in the bin directory which will allow you change more settings, such as the JVM the service uses.

if you use a custom name for your service, rename (or copy) TomEE.exe to match it - e.g. TomEE-DEV.exe to match the examples above.

Using a 32 bit JVM on 64 bit Windows

The service script will install either TomEE.x86.exe or TomEE.amd64.exe as the service. The script uses the PROCESSOR_ARCHITECTURE=AMD64 environment variable to determine which to use. The TomEE executable used needs to match the architecture of the JVM you wish to use.

If you wish to use a 32 bit JVM on 64 bit Windows, run

set PROCESSOR_ARCHITECTURE=X86 prior to installing the service.

Setting environment variables for the service

Setting custom environment variables for TomEE to use is a little tricky as it can’t be done through the UI, but can be accomplished via the command line.

After the service as been installed, at the Command Prompt, use the following syntax (use the right TomEE exe for your platform)

TomEE.amd64.exe //US//TomEE ++Environment "variable=value"

Replace TomEE after //US// with your service name if you are using a custom service name.

Further information

The TomEE exe files are from the Apache Commons Daemon project. Full documentation for commons-daemon can be found here:

http://commons.apache.org/proper/commons-daemon/procrun.html