Home | Send Feedback

Java application as Windows Service

Published: May 06, 2020  •  java

In this blog post, I show you how to install a Java application with WinSW as a Windows service. WinSW is an executable binary, which can be used to wrap and manage any custom process as a Windows service.

Demo

First, we need a demo application. I use a simple Quarkus application for this purpose. You can install any Java application as a service. Usually, you install applications that run forever like an HTTP server in this case.

To bootstrap a Quarkus application run this command

mvn io.quarkus:quarkus-maven-plugin:1.4.2.Final:create -DprojectGroupId=com.testlab -DprojectArtifactId=testservice -DclassName="com.testlab.testservice.GreetingResource" -Dpath="/hello"
cd testservice

We use the application as is with just a small change. I want to create a fat jar. A jar with all dependent libraries included.
You can package your application in any way you want. In this case, I prefer the fat jar installation because I only have to copy one file.

Open src\main\resources\application.properties and insert the following property

quarkus.package.uber-jar=true

Now you can package the application with .\mvnw.cmd package. You find the jar in the target folder. Here it's named testservice-1.0-SNAPSHOT-runner.jar.

Preparation

You can proceed in different ways. I usually create a special folder where I copy all the files into it that are needed to run the application as a service. Copy the jar from the target folder into this directory.

Java

Next, I download the Java Runtime Environment (JRE) and also copy it into this folder. This is optional. Your service can access a globally installed Java. But I like to have everything contained in one folder and don't have to worry about somebody updating or removing the globally installed Java.

I usually download the JRE from AdoptOpenJDK. On the release page, you find the ZIP file with the JRE.

Here the URL for Java 14:
https://adoptopenjdk.net/releases.html?variant=openjdk14&jvmVariant=hotspot

Download the ZIP file and unzip it into the install folder. I unzip it into the jre subfolder, so the java.exe is accessible with this path jre\bin\java.exe


WinSW

Open the release page of the WinSW project and download the executable suitable for your platform.
https://github.com/winsw/winsw/releases

For this demo installation, I download WinSW.NET461.exe. WinSW runs on Windows with .NET Framework 2.0, 4.0 or 4.6.1. If you need to install the service on a Windows without .NET framework, download the core variant WinSW.NETCore31.x64.exe for 64-bit or WinSW.NETCore31.x86.exe for 32-bit systems. The core executables are based on .NET Core 3.1

Copy the executable also into the folder where your jar resided. Rename the WinSW executable to any name you like. For this example, I rename it to testservice.exe. Create an XML with the same base name: testservice.xml. Make sure that the exe and XML file are located in the same folder.

Open the XML file and paste the following code into it.

<service>
  <id>testservice</id>
  <name>Test Service</name>
  <description>This is a test service.</description>
  <executable>"%BASE%\jre\bin\java"</executable>
  <arguments>-jar "%BASE%\testservice-1.0-SNAPSHOT-runner.jar"</arguments>
  <logmode>rotate</logmode>
  <stopparentprocessfirst>true</stopparentprocessfirst>
</service>

Check the executables path and arguments. %BASE% is an environment variable that points to the directory where the WinSW executable is located. If you want to start the application with a Java that is on the %PATH%, just use <executable>java</executable>.

Relevant here is <stopparentprocessfirst>. This tells WinSW to shutdown the parent process first. In our case this is useful because the main process opens a console (java), which can respond to Ctrl+C and will gracefully shutdown the child process (the Java application).

Check out this wiki page to learn more about all the supported options:
https://github.com/winsw/winsw/blob/master/doc/xmlConfigFile.md

Directory structure

The directory structure of my install folder.

testservice.exe
testservice.xml
testservice-1.0-SNAPSHOT-runner.jar
jre
  bin
    java.exe
    ...
  conf
  legal
  lib
  ...

Installation

With everything in place you install the Windows service with this command

testservice.exe install

The WinSW command supports the following options:

The service by default is installed with start mode Automatic. That means Windows starts the service when it boots up. You can change that with the <startmode> configuration in the XML file.

  <startmode>Manual</startmode>

To test the installation, open http://localhost:8080 in a browser. You should see the default start page of Quarkus. To test if the graceful shutdown works, stop the service

testservice stop

Open the file testservice.out.log.

2020-05-06 05:30:52,501 INFO  [io.quarkus] (main) Profile prod activated. 
2020-05-06 05:30:52,501 INFO  [io.quarkus] (main) Installed features: [cdi, resteasy]
2020-05-06 05:30:54,801 INFO  [io.quarkus] (main) testservice stopped in 0.032s

We see that the application shutdown gracefully because of the testservice stopped log entry.

Note that WinSW creates by default three logs files:


That concludes this tutorial about installing any Java applications as Windows Service. Optionally you could try and create a native image of your application with GraalVM. The service installation does not change a lot. You don't need the JRE anymore and have to change <executable> accordingly.