Introduction

The Spring Boot project is great way of building Java applications using Spring. Instead of trying to integrate everything by hand (and usually end up with a configuration hell) you use spring-boot to help you to bootstrap your application: Just include its dependencies in your pom.xml and Spring Boot will try its best to auto-configure all these components!

Of course, no matter how hard Spring Boot tries to auto-configure everything, you’ll still need to pass some configuration to configure your databases, caches, email sending, security etc. Thankfully, Spring Boot can be configured without any xml (actually, its a bad practice to use xml-based configuration with it), using plain Java .properties files or (if you prefer the more compact syntax) YAML .yml files!

In this guide, along with a simple introduction to the way Spring Boot configuration works, we’ll talk about a specific way of stucturing your settings configuration files in order to have:

• A global configuration file that will contain all your settings
• Different settings for each of your environments (development, UAT, staging, production and test)
• A way to configure your passwords and other sensitive data (that you don’t want to put to your VCS)
• Being able to override any setting in any environment
• Deploying your Spring Boot app in Linux using init.d

To quickly test the proposed settings configuration I’ve created a simple Spring Boot project @ https://github.com/spapas/spring-boot-config. Just clone it, optionally change the packaged settings (more on this later), package it (mvn package), optionally change the config settings (more on this also later) and run it (using something like java -jar spring-boot-config-0.0.1-SNAPSHOT.jar) optionally passing it command line settings (more on this also later). You’ll then be able to visit http://127.0.0.1:8080 and check the current settings!

properties vs yml files

You can use two kinds of files to configure your settings: Normal Java .properties files or YAML .yml files. The .properties files have the form:

config.value.a=1
config.value.b=2
config.value.c=3

while the .yml files are like:

config:
    value:
        a: 1
        b: 2
        c: 3

You may use whatever you wish - in the examples I’ll use normal Java .properties files because they are more compact (you don’t need to use multiple lines to represent a single setting like in YAML).

Structuring your configuration files

Spring Boot reads its configuration from various places, however in this article we’ll talk about four of them which should be enough for most cases. Starting from the most global to the most specific ones (i.e the latter ones will override the previous ones) these are:

• Main (global) application settings
• Profile settings
• Local (/config) settings
• Command line arguments

The first two are setting files that will be contained inside the artifact (jar or war) that will be created and should be commited to your version control system. I’ll call them jar-packaged settings. The other two won’t be commited to the version control but will be created directly on the server to-deploy. Let’s see a little more about them:

@RunWith(SpringJUnit4ClassRunner.class)
@SpringApplicationConfiguration(classes = SpringBootConfigApplication.class)
@ActiveProfiles("test")
public class SpringBootConfigApplicationTests {

    @Value("${config.value}")
    private String value;

    @Value("${spring.profiles.active}")
    private String profile;

    @Test
    public void contextLoads() {
        assertThat(value, is("Hello test!"));
        assertThat(profile, is("test"));
    }
}

Deploying Spring Boot applications

If you check the deployment documentation of Spring Boot you’ll see that it has various hints on on deploying Spring Boot applications. I won’t go into much detail about these however I’ll represent my recommendation on deploying Spring Boot apps on Linux as an init.d script:

What is really interesting about Spring boot is that it allows you to make your jar-packaged jars executable as an init.d script so that you will be able to manage it using something like service springbootapp start/stop/restart etc. To do that, you’ll just need to add the <executable>true</executable> configuration for your pom’s spring-boot-maven-plugin. This will add some things in the start of your resulting jar file that will make it behave as a unix init.d script. If you take a look at your package artifact you’ll see something like this:

#!/bin/bash
#
#    .   ____          _            __ _ _
#   /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
#  ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
#   \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
#    '  |____| .__|_| |_|_| |_\__, | / / / /
#   =========|_|==============|___/=/_/_/_/
#   :: Spring Boot Startup Script ::
#

### BEGIN INIT INFO
# Provides:          spring-boot-config
# Required-Start:    $remote_fs $syslog $network
# Required-Stop:     $remote_fs $syslog $network
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: spring-boot-config
# Description:       Demo project for Spring Boot configuration
# chkconfig:         2345 99 01
### END INIT INFO

[[ -n "$DEBUG" ]] && set -x

# Initialize variables that cannot be provided by a .conf file
WORKING_DIR="$(pwd)"
# shellcheck disable=SC2153
[[ -n "$JARFILE" ]] && jarfile="$JARFILE"
[[ -n "$APP_NAME" ]] && identity="$APP_NAME"

...

One thing that may seem puzzling at first is that if make this jar executable and try to run it you’ll see that, instead of offering you the well known options of the init scripts (Usage … start/stop/restart etc) it will immediatelly run the application! This is because the embedded script is smart enough to check that it will be executed as an init script only when it is executed as a link from /etc/init.d - else it will immediately run the application.

If you want to quickly test that behavior, you may override the MODE parameter which forces the mode of operation of the jar. If you want to run it as a script (without using a links from /etc/ini.d) then just set MODE=service. So, try runnin:

> MODE=service ./springapplication.jar
Usage: ./hsk9eea.jar {start|stop|restart|force-reload|status|run}

Success! Of course, this is just for testing purposes, to actually deploy your application then please create a link to it from /etc/init.d as proposed by the Spring Boot docs.

If you want to customize the init.d script you can use a file named sprinbootapp.conf in the same directory as your springbootapp.jar (i.e it should have the same name as your jar with an extension of .conf). The options from it will be sourced before running your application — for example you could set the active profile using RUN_ARGS, however as I already recommended, explicitly setting it to a file named config/applications.properties is preferrable.

Conclusion

Using the described file structure you should be able to fully configure Spring Boot and have all the goodies you’d expect from a modern framework: global settings, profiles, non-version control settings! Also, using the advanced profiles techniques (multiple profiles, profile enabled @Components and @Configurations) you’ll be able to implement some really complex configurations! Finally, you’ll be able to really quickly deploy the resulting jar as an init.d system service!