Spring Boot Application as a Service

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:

<packaging>jar</packaging>

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>1.4.0.RELEASE</version>
</parent>

<dependencies>
    ....
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <configuration>
                <executable>true</executable>
            </configuration>
        </plugin>
    </plugins>
</build>

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 <executable> 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:

$ mvn clean package

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:

$ java -jar your-app.jar

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:

$ sudo useradd baeldung
$ sudo passwd baeldung
$ sudo chown baeldung:baeldung your-app.jar
$ sudo chmod 500 your-app.jar

3.1. System V Init

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

$ sudo ln -s /path/to/your-app.jar /etc/init.d/your-app

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:

$ sudo service your-app start

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:

[Unit]
Description=A Spring Boot application
After=syslog.target

[Service]
User=baeldung
ExecStart=/path/to/your-app.jar SuccessExitStatus=143 

[Install] 
WantedBy=multi-user.target

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:

# Place in /home/{user}/.config/upstart

description "Some Spring Boot application"

respawn # attempt service restart if stops abruptly

exec java -jar /path/to/your-app.jar

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:

<service>
    <id>MyApp</id>
    <name>MyApp</name>
    <description>This runs Spring Boot as a Service.</description>
    <env name="MYAPP_HOME" value="%BASE%"/>
    <executable>java</executable>
    <arguments>-Xmx256m -jar "%BASE%\MyApp.jar"</arguments>
    <logmode>rotate</logmode>
</service>

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:

$ MyApp.exe install

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.