Deploying Spring Boot apps as Windows Services

Aug 3, 2018 · 4 min read

Spring Boot is cool. It makes application development using java and the spring framework a breeze. It even packages your java app into an executable uber jar with it’s own embedded application server (tomcat) ready to go, giving you a truly self contained micro-service. And when it’s time to deploy your application, all you have to do is open up a command terminal (on windows) and execute

and just like that, your helloworld.jar app is live!

However this has always b een my biggest concern with deploying spring boot apps on windows machines. It seems you must have a command window open at all times. What if someone accidentally closes the window while your app is running? That doesn’t sound good. There has to be a better way, We already have an executable uber jar. Why can’t we take it a step further and make it a windows service? At least that way we won’t have to bother about accidental shutdowns, and even if that happens, we have a way of automatically restarting the app.

Enter NSSM

After a bit of googling how to convert java applications to windows services, I finally settled for NSSM (The non-sucking service manager). NSSM is good. Easy to use and straight to the point. You run the command

and it opens up a nice little GUI wizard to guide you through the service creation process. In my case I had to create a .bat file that executes my spring boot app with java -jar and then install the .bat as a service using NSSM.

The Problem

So far my Spring Boot app is running great as a windows service until it’s time to stop the service. For some reason, The service experiences difficulty stopping completely when I click on stop service, and I always have to manually terminate the java windows processes running it.

The Solution: WINSW With Spring Boot Stopper

Leveraging Spring Boot’s admin features, we can expose the SpringApplicationAdminMXBean on the platform MBeanServer to provide us a way of gracefully shutting down our application via JMS. And that’s where Spring Boot Stopper comes in. Spring boot stopper simply calls our application’s JMS shutdown URL to trigger the application shutdown.

Winsw does just what nssm does and more. It enables us wrap any windows executable as a windows service. More importantly, it provides option for specifying command to run when the service is stopped. For a full guide on how to use winsw to wrap an executable check out the project’s github page.

Now what we want to achieve are twofold:

1. Start our spring boot application with JMS admin features enabled and listening on a particular port. Note this exposes your service to the risk of being stopped by anybody with the right JMS URL and port.
2. Tell winsw to execute Spring Boot Stopper when we stop the service and pass our application’s JMS port as argument.

Sample winsw configuration to achieve this scenario:

From the configuration XML above you will notice the following among others:

1. We used the tag to specify which windows executable to execute when the service starts.
2. We used to define %BASE% (which translates to the folder containing this config) as the working directory for the executable.
3. We passed a number of to the executable. These are used as command line arguments when the service starts. The parameters we passed here are to specify the java .jar file to execute (helloworld.jar , enable JMS, set the JMS port (we are using 54321 as our JMS port), and disable JMS authentication and SSL.
4. Lastly we used to define what actions to take when the service is stopped. In this case we want winsw to run java -jar SpringBootStopper.jar 54321 .

That done, to finally get our helloworld service installed and running:

1. We create a folder in the location we want our application to reside.
2. Then we drop the following files in the folder: SpringBootStopper.jar, helloworld.jar, the .xml file containing the configurations from above, and the winsw.exe file.
3. Next we rename the xml file to helloworld.xml and rename the winsw.exe file to helloworld.exe.
4. The winsw executable, the configuration file and the application jar file must have the same name for winsw to function properly.
5. Next we open a command terminal and navigate to the folder containing the files, then execute helloworld.exe install . This creates the windows service with the name specified in the configuration file. A logs folder will also be created in the service root folder.
6. Lastly we go to the windows service manager to look for our service (Hello World) and start it. The log files generated by application will be in the logs folder.

And that’s it! Our spring boot application has been successfully configured and installed as a windows service.

To stop the application all we have to do is go to the windows service manager and stop the Hello World service.

No more worries about an always open command terminal and accidentally closing the terminal.

Additionally we can also set the windows service as automatic so that it always start whenever windows is restarted. This way we are fairly sure our application will always be running as long as windows is running. Unless some major application runtime error is encountered :D.

Congratulations! You’ve made it to the end of this post!

If you like this post or find it interesting please don’t hesitate to give it a clap or two or three, you know you can just keep clapping, I’ll appreciate. Also feel free to share it!

Spring Boot Application as a Service

Last modified: June 25, 2020

If you have a few years of experience in the Java ecosystem, and you’re interested in sharing that experience with the community (and getting paid for your work of course), have a look at the «Write for Us» page. Cheers, Eugen

1. Overview

This article explores some options of running Spring Boot applications as a service.

Firstly, we are going to explain web applications’ packaging options and system services. In the subsequent sections, we explore different alternatives we have when setting up a service for both Linux as Windows based systems.

Finally, we will conclude with some references to additional sources of information.

2. Project Setup and Build Instructions

2.1. Packaging

Web applications are traditionally packaged as a Web Application aRchives (WAR) and deployed to a web server.

Spring Boot applications may be packaged both as WAR and JAR files. The latter embeds a web server within a JAR file, which allows you to run applications without the need of an installation and configuration of an application server.

2.2. Maven Configuration

Let’s start by defining the configuration of our pom.xml file:

The packaging must be set to jar. We are using the latest stable version of Spring Boot at the time of writing, but any version after 1.3 will be enough. You can find more information about available versions here.

Notice that we have set the parameter to true for the spring-boot-maven-plugin artifact. This makes sure that a MANIFEST.MF file is added to the JAR package. This manifest contains a Main-Class entry that specifies which class defines the main method for your application.

2.3. Building Your Application

Run the following command inside your application’s root directory:

The executable JAR file is now available in the target directory and we may start up the application by executing the following command on the command line:

At this point, you still need to invoke the Java interpreter with the -jar option. There are many reasons why it would be preferable to have your app started by being able to invoke it as a service.

3. On Linux

In order to run a program as a background process, we could simply use the nohup Unix command, but this is not the preferred way either for various reasons. A good explanation is provided in this thread.

Instead, we are going to daemonize our process. Under Linux, we may choose to configure a daemon either with a traditional System V init script or with a Systemd configuration file. The former is traditionally the most well-known option but is gradually being replaced by the latter.

You may find more details on this difference here.

For enhanced security we first create a specific user to run the service with and change the executable JAR file permissions accordingly:

3.1. System V Init

A Spring Boot executable JAR file makes the service setup process very easy:

The above command creates a symbolic link to your executable JAR file. You must use the full path to your executable JAR file, otherwise, the symbolic link will not work properly. This link enables you to start the application as a service:

The script supports the standard service start, stop, restart and status commands. Moreover:

• it starts the services running under the user baeldung we have just created
• it tracks the application’s process ID in /var/run/your-app/your-app.pid
• it writes console logs to /var/log/your-app.log, which you may want to check in case your application fails to start properly

3.2. Systemd

The systemd service setup is very simple as well. Firstly, we create a script named your-app.service using the following example and put it in /etc/systemd/system directory:

Remember to modify Description, User and ExecStart fields to match your application. You should be able to execute the aforementioned standard service commands at this point as well.

As opposed to the System V init approach described in the previous section, the process ID file and console log file should be configured explicitly using appropriate fields in the service script. An exhaustive list of options may be found here.

3.3. Upstart

Upstart is an event-based service manager, a potential replacement for the System V init that offers more control on the behavior of the different daemons.

The site has good setup instructions that should work for almost any Linux distribution. When using Ubuntu you probably have it installed and configured already (check if there are any jobs with a name starting with “upstart” in /etc/init).

We create a job your-app.conf to start our Spring Boot application:

Now run “start your-app” and your service will start.

Upstart offers many job configuration options, you can find most of them here.

4. On Windows

In this section, we present a couple of options that may be used to run a Java JAR as a Windows service.

4.1. Windows Service Wrapper

Due to difficulties with the GPL license of the Java Service Wrapper (see next subsection) in combination with e.g. the MIT license of Jenkins, the Windows Service Wrapper project, also known as winsw, was conceived.

Winsw provides programmatic means to install/uninstall/start/stop a service. In addition, it may be used to run any kind of executable as a service under Windows, whereas Java Service Wrapper, as implied by its name, only supports Java applications.

First, you download the binaries here. Next, the configuration file that defines our Windows service, MyApp.xml, should look like this:

Finally, you have to rename the winsw.exe to MyApp.exe so that its name matches with the MyApp.xml configuration file. Thereafter you can install the service like so:

Similarly, you may use uninstall, start, stop, etc.

4.2. Java Service Wrapper

In case you don’t mind the GPL licensing of the Java Service Wrapper project, this alternative may address your needs to configure your JAR file as a Windows service equally well. Basically, the Java Service Wrapper also requires you to specify in a configuration file which specifies how to run your process as a service under Windows.

This article explains in a very detailed way how to set up such an execution of a JAR file as a service under Windows, so we there’s no need to repeat the info.

5. Additional References

Spring Boot applications may also be started as Windows service using Procrun of the Apache Commons Daemon project. Procrun is a set of applications that allow Windows users to wrap Java applications as Windows services. Such a service may be set to start automatically when the machine boots and will continue to run without any user being logged on.

More details on starting Spring Boot applications under Unix may be found here. There are also detailed instructions on how to modify Systemd unit files for Redhat based systems. Finally

Finally, this quick howto describes how to incorporate a Bash script into your JAR file, so that it becomes an executable itself!

6. Conclusion

Services allow you to manage your application state very efficiently and, as we have seen, service setup for Spring Boot applications is now easier than ever.

Just remember to follow the important and simple security measures on user permissions to run your service.

Spring boot JAR as windows service

I am trying to wrap a spring boot «uber JAR» with procrun.

Running the following works as expected:

I need my spring boot jar to automatically start on windows boot. The nicest solution for this would be to run the jar as a service (same as a standalone tomcat).

When I try to run this I am getting «Commons Daemon procrun failed with exit value: 3»

Looking at the spring-boot source it looks as if it uses a custom classloader:

I also get a «ClassNotFoundException» when trying to run my main method directly.

Is there a method I can use to run my main method in a spring boot jar (not via JarLauncher)?

Has anyone successfully integrated spring-boot with procrun?

I am aware of http://wrapper.tanukisoftware.com/. However due to their licence I can’t use it.

UPDATE

I have now managed to start the service using procrun.

I now just need to workout how to stop the service. I am thinking of doing someting with the spring-boot actuator shutdown JMX Bean.

What happens when I stop the service at the moment is; windows fails to stop the service (but marks it as stopped), the service is still running (I can browse to localhost), There is no mention of the process in task manager (Not very good! unless I am being blind).

5 Answers 5

I ran into similar issues but found someone else (Francesco Zanutto) was gracious enough to write a blog post about their efforts. Their solution worked for me. I take no credit for the time they put into realizing this code.

He’s using the jvm start and stop mode, compared to the exe mode I see in your example. With this, he’s able to extend Spring Boot’s JarLauncher to handle both «start» and «stop» commands from Windows services’ which I believe you’re looking to do for a graceful shutdown.