54. Installing Spring Boot applications
Prev Part VI. Deploying Spring Boot applications Next

54. Installing Spring Boot applications

In additional to running Spring Boot applications using java -jar it is also possible to make fully executable applications for Unix systems (Linux, OSX, FreeBSD etc). This makes it very easy to install and manage Spring Boot applications in common production environments. As long as you are generating ‘fully executable’ jars from your build, and you are not using a custom embeddedLaunchScript, the following techniques can be used.

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

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

With Gradle, the equivalent configuration would be:

apply plugin: 'spring-boot'

springBoot {
    executable = true
}
[Note]Note

Fully executable jars work by embedding an extra script at the front of the file. Not all tools currently accept this format so you may not always be able to use this technique.

54.1 Unix/Linux services

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

54.1.1 Installation as a init.d service (System V)

The default executable script that can be embedded into Spring Boot jars will act as an init.d script when it is symlinked to /etc/init.d. The standard start, stop, restart and status commands can be used. The script supports the following features:

  • Starts the services as the user that owns the jar file
  • Tracks application PIDs 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
[Tip]Tip

It is advisable to create a specific user account to run you application. Ensure that you have set the owner of the jar file using chown before installing your service.

Once installed, you can start and stop the service in the usual way. You can also flag the application to start automatically using your standard operating system tools. For example, if you use Debian:

$ update-rc.d myapp defaults <priority>

54.1.2 Installation as a systemd service

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

For example, to run a Spring Boot application installed in var/myapp you can add the following script in /etc/systemd/system/myapp.service:

[Unit]
Description=myapp
After=syslog.target

[Service]
ExecStart=/var/myapp/myapp.jar

[Install]
WantedBy=multi-user.target
[Tip]Tip

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

54.1.3 Customizing the startup script

The script accepts the following parameters as environment variables, so you can change the default behavior in a script or on the command line:

VariableDescription

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.

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).

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.

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.

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.

[Tip]Tip

With the exception of JARFILE and APP_NAME, the above settings can be placed in a .conf next to the jar. For example the jar /var/myapp/myapp.jar would attempt to source the configuration file /var/myapp/myapp.conf.

Prev Up Next
53. Deploying to the cloud Home 55. What to read next