59. Installing Spring Boot applications

In addition to running Spring Boot applications using java -jar it is also possible
to make fully executable applications for Unix systems. A fully executable jar can be
executed like any other executable binary or it can be registered
with init.d or systemd. This makes it very easy to install and manage Spring Boot
applications in common production environments.

Warning

Fully executable jars work by embedding an extra script at the front of the
file. Currently, some tools do not accept this format so you may not always be able to
use this technique. For example, jar -xf may silently fail to extract a jar or war that
has been made fully-executable. It is recommended that you only make your jar or war
fully executable if you intend to execute it directly, rather than running it with
java -jar or deploying it to a servlet container.

To create a ‘fully executable’ jar with Maven use the following plugin configuration:

You can then run your application by typing ./my-application.jar (where
my-application is the name of your artifact). The directory containing the
jar will be used as your application’s working directory.

59.1 Supported operating systems

The default script supports most Linux distributions and is tested on CentOS and
Ubuntu. Other platforms, such as OS X and FreeBSD, will require the use of a custom
embeddedLaunchScript.

59.2 Unix/Linux services

Spring Boot application can be easily started as Unix/Linux services using either init.d
or systemd.

59.2.1 Installation as an init.d service (System V)

If you’ve configured Spring Boot’s Maven or Gradle plugin to generate a
fully executable jar, and you’re not using a custom
embeddedLaunchScript, then your application can be used as an init.d service. Simply
symlink the jar to init.d to support the standard start, stop, restart and
status commands.

The script supports the following features:

Starts the services as the user that owns the jar file

Tracks application’s PID using /var/run/<appname>/<appname>.pid

Writes console logs to /var/log/<appname>.log

Assuming that you have a Spring Boot application installed in /var/myapp, to install a
Spring Boot application as an init.d service simply create a symlink:

$ sudo ln -s /var/myapp/myapp.jar /etc/init.d/myapp

Once installed, you can start and stop the service in the usual way. For example, on a
Debian based system:

$ service myapp start

Tip

If your application fails to start, check the log file written to
/var/log/<appname>.log for errors.

You can also flag the application to start automatically using your standard operating
system tools. For example, on Debian:

$ update-rc.d myapp defaults <priority>

Securing an init.d service

Note

The following is a set of guidelines on how to secure a Spring Boot application
that’s being run as an init.d service. It is not intended to be an exhaustive list of
everything that should be done to harden an application and the environment in which it
runs.

When executed as root, as is the case when root is being used to start an init.d service,
the default executable script will run the application as the user which owns the jar
file. You should never run a Spring Boot application as root so your application’s jar
file should never be owned by root. Instead, create a specific user to run your
application and use chown to make it the owner of the jar file. For example:

$ chown bootapp:bootapp your-app.jar

In this case, the default executable script will run the application as the bootapp
user.

Tip

To reduce the chances of the application’s user account being compromised, you should
consider preventing it from using a login shell. Set the account’s shell to
/usr/sbin/nologin, for example.

You should also take steps to prevent the modification of your application’s jar file.
Firstly, configure its permissions so that it cannot be written and can only be read or
executed by its owner:

$ chmod 500 your-app.jar

Secondly, you should also take steps to limit the damage if your application or the
account that’s running it is compromised. If an attacker does gain access, they could make
the jar file writable and change its contents. One way to protect against this is to make
it immutable using chattr:

$ sudo chattr +i your-app.jar

This will prevent any user, including root, from modifying the jar.

If root is used to control the application’s service and you
use a .conf file to customize its
startup, the .conf file will be read and evaluated by the root user. It should be
secured accordingly. Use chmod so that the file can only be read by the owner and use
chown to make root the owner:

$ chmod 400 your-app.conf
$ sudo chown root:root your-app.conf

59.2.2 Installation as a systemd service

Systemd is the successor of the System V init system, and is now being used by many modern
Linux distributions. Although you can continue to use init.d scripts with systemd, it
is also possible to launch Spring Boot applications using systemd ‘service’ scripts.

Assuming that you have a Spring Boot application installed in /var/myapp, to install a
Spring Boot application as a systemd service create a script named myapp.service using
the following example and place it in /etc/systemd/system directory:

Remember to change the Description, User and ExecStart fields for your
application.

Tip

Note that ExecStart field does not declare the script action command, which means
that run command is used by default.

Note that unlike when running as an init.d service, user that runs the application, PID
file and console log file are managed by systemd itself and therefore must be configured
using appropriate fields in ‘service’ script. Consult the
service unit
configuration man page for more details.

To flag the application to start automatically on system boot use the following command:

$ systemctl enable myapp.service

Refer to man systemctl for more details.

59.2.3 Customizing the startup script

The default embedded startup script written by the Maven or Gradle plugin can be
customized in a number of ways. For most people, using the default script along with
a few customizations is usually enough. If you find you can’t customize something that
you need to, you can always use the embeddedLaunchScript option to write your own
file entirely.

Customizing script when it’s written

It often makes sense to customize elements of the start script as it’s written into the
jar file. For example, init.d scripts can provide a “description” and, since you know
this up front (and it won’t change), you may as well provide it when the jar is generated.

To customize written elements, use the embeddedLaunchScriptProperties option of the
Spring Boot Maven or Gradle plugins.

The following property substitutions are supported with the default script:

Name

Description

mode

The script mode. Defaults to auto.

initInfoProvides

The Provides section of “INIT INFO”. Defaults to spring-boot-application for Gradle
and to ${project.artifactId} for Maven.

The Short-Description section of “INIT INFO”. Defaults to Spring Boot Application
for Gradle and to ${project.name} for Maven.

initInfoDescription

The Description section of “INIT INFO”. Defaults to Spring Boot Application for
Gradle and to ${project.description} (falling back to ${project.name}) for Maven.

initInfoChkconfig

The chkconfig section of “INIT INFO”. Defaults to 2345 99 01.

confFolder

The default value for CONF_FOLDER. Defaults to the folder containing the jar.

logFolder

The default value for LOG_FOLDER. Only valid for an init.d service.

logFilename

The default value for LOG_FILENAME. Only valid for an init.d service.

pidFolder

The default value for PID_FOLDER. Only valid for an init.d service.

pidFilename

The default value for the name of the pid file in PID_FOLDER. Only valid for an
init.d service.

useStartStopDaemon

If the start-stop-daemon command, when it’s available, should be used to control the
process. Defaults to true.

stopWaitTime

The default value for STOP_WAIT_TIME. Only valid for an init.d service.
Defaults to 60 seconds.

Customizing script when it runs

For items of the script that need to be customized after the jar has been written you
can use environment variables or a
config file.

The following environment properties are supported with the default script:

Variable

Description

MODE

The “mode” of operation. The default depends on the way the jar was built, but will
usually be auto(meaning it tries to guess if it is an init script by checking if it
is a symlink in a directory called init.d). You can explicitly set it to service so
that the stop|start|status|restart commands work, or to run if you just want to
run the script in the foreground.

USE_START_STOP_DAEMON

If the start-stop-daemon command, when it’s available, should be used to control the
process. Defaults to true.

PID_FOLDER

The root name of the pid folder (/var/run by default).

LOG_FOLDER

The name of the folder to put log files in (/var/log by default).

CONF_FOLDER

The name of the folder to read .conf files from (same folder as jar-file by default).

LOG_FILENAME

The name of the log file in the LOG_FOLDER (<appname>.log by default).

APP_NAME

The name of the app. If the jar is run from a symlink the script guesses the app name,
but if it is not a symlink, or you want to explicitly set the app name this can be
useful.

RUN_ARGS

The arguments to pass to the program (the Spring Boot app).

JAVA_HOME

The location of the java executable is discovered by using the PATH by default, but
you can set it explicitly if there is an executable file at $JAVA_HOME/bin/java.

JAVA_OPTS

Options that are passed to the JVM when it is launched.

JARFILE

The explicit location of the jar file, in case the script is being used to launch a jar
that it is not actually embedded in.

DEBUG

if not empty will set the -x flag on the shell process, making it easy to see the logic
in the script.

STOP_WAIT_TIME

The time in seconds to wait when stopping the application before forcing a shutdown
(60 by default).

Note

The PID_FOLDER, LOG_FOLDER and LOG_FILENAME variables are only valid for an
init.d service. With systemd the equivalent customizations are made using ‘service’
script. Check the
service unit
configuration man page for more details.

With the exception of JARFILE and APP_NAME, the above settings can be configured using
a .conf file. The file is expected next to the jar file and have the same name but
suffixed with .conf rather than .jar. For example, a jar named /var/myapp/myapp.jar
will use the configuration file named /var/myapp/myapp.conf.

myapp.conf.

JAVA_OPTS=-Xmx1024M
LOG_FOLDER=/custom/log/folder

Tip

You can use a CONF_FOLDER environment variable to customize the location of the
config file if you don’t like it living next to the jar.