Quick SpringBoot Integration (Windows)

SpringBoot 4.1.x Integration

This section describes the steps to get up and running quickly with SpringBoot 4.1.0. Other versions should work in a similar way.

This configuration is based on launching a SpringBoot application as a standalone server.

Build your SpringBoot Application

SpringBoot is not downloaded as a standalone server. This document assumes that you are able to build your SpringBoot executable fat jar.

For this example, we will use the gs-spring-boot project, which is a simple hello world application. Clone a local copy of the repository. Navigate into the project's complete directory and run mvn package. This will create a file: target/spring-boot-complete-0.0.1-SNAPSHOT.jar

Create a sibling directory spring-boot-complete into which we will build the application. Copy the above executable jar into this directory as spring-boot-complete/lib/spring-boot-complete-0.0.1-SNAPSHOT.jar

Download Wrapper

The following steps are designed to work with version 3.7.0 of the Java Service Wrapper. Using earlier versions is possible, but will likely require some changes.

Decide which edition to use (Professional, Standard, or Community), and select the target platform, bitness, and architecture. Then download the installer or archive and install or extract it. We will assume you are using the Professional 64-bit Edition on Linux x86.

Wrapper Integration

To ease the placement of required Wrapper files, create the following PowerShell script in your spring-boot-complete directory as updateWrapper.ps1. Update the location where you installed or extracted the Wrapper above. 

$WRAPPER_HOME = "../wrapper-windows-x86-64-3.7.0-pro"
$SBAPP_HOME = "."
$WRAPPER_SCRIPT = "service.bat"

[void](New-Item -ItemType Directory -Force -Path "${SBAPP_HOME}/bin")
[void](New-Item -ItemType Directory -Force -Path "${SBAPP_HOME}/lib")
if (Test-Path "$WRAPPER_HOME/lang" -PathType Container) {
    [void](New-Item -ItemType Directory -Force -Path "${SBAPP_HOME}/lang")
    Copy-Item -Path "$WRAPPER_HOME/lang/wrapper_*.mo" -Destination "$SBAPP_HOME/lang/"
    Copy-Item -Path "$WRAPPER_HOME/lang/wrapperjni_*.mo" -Destination "$SBAPP_HOME/lang/"
}
[void](New-Item -ItemType Directory -Force -Path "${SBAPP_HOME}/conf")
if (Test-Path "$WRAPPER_HOME/src/conf/wrapper-license-time.conf" -PathType Leaf) {
    Copy-Item -Path "$WRAPPER_HOME/src/conf/wrapper-license-time.conf" -Destination "$SBAPP_HOME/conf/wrapper-license.conf"
}
[void](New-Item -ItemType Directory -Force -Path "${SBAPP_HOME}/logs")

Copy-Item -Path "$WRAPPER_HOME/bin/wrapper.exe" -Destination "$SBAPP_HOME/bin/" -Force
Copy-Item -Path "$WRAPPER_HOME/lib/wrapper.jar" -Destination "$SBAPP_HOME/lib/" -Force
Copy-Item -Path "$WRAPPER_HOME/lib/wrapper.dll" -Destination "$SBAPP_HOME/lib/" -Force
Copy-Item -Path "$WRAPPER_HOME/src/bin/AppCommand.bat.in" -Destination "$SBAPP_HOME/bin/$WRAPPER_SCRIPT" -Force

Run the script: 

./updateWrapper.ps1

NOTE

If PowerShell reports that script execution is disabled, run: 

powershell.exe -ExecutionPolicy Bypass -File .\updateWrapper.ps1

This bypass applies only to that invocation and does not modify your PowerShell configuration.


The configuration uses Integration Method 4.

NOTE

The JAVA_HOME must be set, but will default to the system environment if defined there. SpringBoot 4.1.x series requires a minimum of Java 17 be specified.

Create the Wrapper configuration file as conf/wrapper.conf with the following content: 

@encoding=UTF-8
# The configuration file must begin with a line declaring its encoding.

# Default mode for file inclusions
@include.default_mode=required

# Include file problems can be debugged by removing '#' at the beginning
#  of the following line:
#@include.debug

#********************************************************************
# Wrapper License Properties (Ignored by Community Edition)
#********************************************************************
# Professional and Standard Editions of the Wrapper require a valid
#  License Key to start.  Licenses can be purchased or a trial license
#  requested on the following pages:
# https://wrapper.tanukisoftware.com/purchase
# https://wrapper.tanukisoftware.com/trial

# The Wrapper will look for either of the following optional files for a
#  valid License Key.  License Key properties can optionally be included
#  directly in this configuration file.
@include.optional ../conf/wrapper-license.conf
@include.optional ../conf/wrapper-license-%WRAPPER_HOST_NAME%.conf

# The following property will output information about which License Key(s)
#  are being found, and can aid in resolving any licensing problems.
#wrapper.license.debug=TRUE

#********************************************************************
# Environment
#********************************************************************
set.default.JAVA_HOME=(SetMe)

#********************************************************************
# Wrapper Localization
#********************************************************************
# Specify the language and locale which the Wrapper should use.
#wrapper.lang=en_US # en_US or ja_JP

# Specify the location of the language resource files (*.mo).
wrapper.lang.folder=../lang

#********************************************************************
# Wrapper Java Properties
#********************************************************************
# Java Application
wrapper.java.command=%JAVA_HOME%/bin/java

# Tell the Wrapper to log the full generated Java command line.
#wrapper.java.command.loglevel=INFO

# Wrapper Jar file
wrapper.jarfile=../lib/wrapper.jar

# Log level for notices about missing Java Classpath entries.
wrapper.java.classpath.missing.loglevel=WARN

# Java Version control
wrapper.java.version.output=true
wrapper.java.version.min=17
#wrapper.java.version.max=

# Java Classpath.  Add class path elements as needed starting from 1
wrapper.java.classpath.1=../lib/*.jar

# Java Modulepath. (Requires Java 9 or above)
#  Add module path elements as needed starting from 1
#wrapper.java.module_path.1=

# Java Module list. (Requires Java 9 or above)
#  Add module names as needed starting from 1
#wrapper.java.module.1=

# Java Library Path (location of wrapper.dll or libwrapper.so)
wrapper.java.library.path.1=../lib

# Java Bits.  On applicable platforms, tells the JVM to run in 32 or 64-bit mode.
wrapper.java.additional.auto_bits=TRUE

# Java Additional Parameters
wrapper.java.additional.1=

# Initial Java Heap Size (in MB)
#wrapper.java.initmemory=3

# Maximum Java Heap Size (in MB)
wrapper.java.maxmemory=256

# Application System Properties passed via the backend.
#  Core Java System Properties must be passed using wrapper.java.additional.<n>.
#wrapper.app.property.1=

# Java Main class.  This class must implement the WrapperListener interface
#  or guarantee that the WrapperManager class is initialized.
#  Helper classes are provided to do this for you.
#  See the following page for details:
#  https://wrapper.tanukisoftware.com/doc/english/integrate.html
wrapper.java.mainclass=org.tanukisoftware.wrapper.WrapperJarApp

# Application parameters.
#  Pass parameters via the backend instead of the command line.
#wrapper.app.parameter.backend=TRUE

#  Add parameters as needed starting from 1
wrapper.app.parameter.1=../lib/spring-boot-complete-0.0.1-SNAPSHOT.jar
    
# Point Spring Boot at external configuration
wrapper.app.parameter.2=--spring.config.location=file:../conf/

# Optional but recommended: also externalize logging config
wrapper.app.parameter.3=--logging.config=file:../conf/logback-spring.xml	

#********************************************************************
# Wrapper Logging Properties
#********************************************************************
# Enables Debug output from the Wrapper.
# wrapper.debug=TRUE

# Format of output for the console.  (See docs for formats)
wrapper.console.format=LPTM

# Log Level for console output.  (See docs for log levels)
wrapper.console.loglevel=INFO

# Log file to use for Wrapper output logging.
wrapper.logfile=../logs/wrapper.log

# Format of output for the log file.  (See docs for formats)
wrapper.logfile.format=LPTM

# Log Level for log file output.  (See docs for log levels)
wrapper.logfile.loglevel=INFO

# Roll mode of the log file.
#  SIZE_OR_WRAPPER causes the file to be rolled whenever its size exceeds the
#  value defined by wrapper.logfile.maxsize, or whenever the Wrapper is
#  launched.
wrapper.logfile.rollmode=SIZE_OR_WRAPPER

# Maximum size that the log file will be allowed to grow to before
#  the log is rolled. Size is specified in bytes.  The default value
#  of 0 disables log rolling.  May abbreviate with the 'k' (kb) or
#  'm' (mb) suffixes.  For example: 10m = 10 megabytes.
wrapper.logfile.maxsize=10m

# Maximum number of rolled log files which will be allowed before old
#  files are deleted.  The default value of 0 implies no limit.
wrapper.logfile.maxfiles=9

# Log Level for sys/event log output.  (See docs for log levels)
wrapper.syslog.loglevel=NONE

#********************************************************************
# Wrapper General Properties
#********************************************************************
# Allow for the use of non-contiguous numbered properties
wrapper.ignore_sequence_gaps=TRUE

# Do not start if the pid file already exists.
wrapper.pidfile.strict=TRUE

# Title to use when running as a console
wrapper.console.title=SpringBoot Server

#********************************************************************
# Wrapper JVM Checks
#********************************************************************
# Detect DeadLocked Threads in the JVM. (Requires Standard Edition)
wrapper.check.deadlock=TRUE
wrapper.check.deadlock.interval=60
wrapper.check.deadlock.action=RESTART
wrapper.check.deadlock.output=FULL

# Out Of Memory detection.
#  Ignore -verbose:class output to avoid false positives.
wrapper.filter.trigger.1000=[Loaded java.lang.OutOfMemoryError
wrapper.filter.action.1000=NONE
#  Ignore -Xlog:class+load=level output to avoid false positives.
wrapper.filter.trigger.1001=[class,load] java.lang.OutOfMemoryError
wrapper.filter.action.1001=NONE
# (Simple match)
wrapper.filter.trigger.1002=java.lang.OutOfMemoryError
# (Only match text in stack traces if -XX:+PrintClassHistogram is being used.)
#wrapper.filter.trigger.1002=Exception in thread "*" java.lang.OutOfMemoryError
#wrapper.filter.allow_wildcards.1002=TRUE
wrapper.filter.action.1002=RESTART
wrapper.filter.message.1002=The JVM has run out of memory.

#********************************************************************
# Wrapper Email Notifications. (Requires Professional Edition)
#********************************************************************
# Common Event Email settings.
#wrapper.event.default.email.debug=TRUE
#wrapper.event.default.email.smtp.host=<SMTP_Host>
#wrapper.event.default.email.smtp.port=25
#wrapper.event.default.email.subject=[%WRAPPER_HOSTNAME%:%WRAPPER_NAME%:%WRAPPER_EVENT_NAME%] Event Notification
#wrapper.event.default.email.sender=<Sender email>
#wrapper.event.default.email.recipient=<Recipient email>

# Configure the log attached to event emails.
#wrapper.event.default.email.maillog=ATTACHMENT
#wrapper.event.default.email.maillog.lines=50
#wrapper.event.default.email.maillog.format=LPTM
#wrapper.event.default.email.maillog.loglevel=INFO

# Enable specific event emails.
#wrapper.event.wrapper_start.email=TRUE
#wrapper.event.jvm_prelaunch.email=TRUE
#wrapper.event.jvm_start.email=TRUE
#wrapper.event.jvm_started.email=TRUE
#wrapper.event.jvm_deadlock.email=TRUE
#wrapper.event.jvm_stop.email=TRUE
#wrapper.event.jvm_stopped.email=TRUE
#wrapper.event.jvm_restart.email=TRUE
#wrapper.event.jvm_failed_invocation.email=TRUE
#wrapper.event.jvm_max_failed_invocations.email=TRUE
#wrapper.event.jvm_kill.email=TRUE
#wrapper.event.jvm_killed.email=TRUE
#wrapper.event.jvm_unexpected_exit.email=TRUE
#wrapper.event.wrapper_stop.email=TRUE

# Specify custom mail content
wrapper.event.jvm_restart.email.body=The JVM was restarted.\n\nPlease check on its status.\n

#********************************************************************
# Wrapper Secure File Properties
#********************************************************************
# To enforce the principle of least privilege for files containing
#  sensitive data, the Wrapper requires that all permissions granted
#  to these files be explicitly allowed in the configuration.
#  Please read the documentation for the full list of properties.

# Allow specific accounts or groups on Windows.
#wrapper.secure_file.check.windows.allowed_account.1=NT AUTHORITY\SYSTEM
#wrapper.secure_file.check.windows.allowed_account.2=BUILTIN\Administrators

# Allow specific groups on Unix systems.
#wrapper.secure_file.check.unix.allowed_group.1=<Group_Of_Users>

# Additional files to check for permissions (Requires Standard Edition)
#wrapper.secure_file.additional.1=<Secured_File>

#********************************************************************
# Wrapper Windows Service Properties
#********************************************************************
# WARNING - Do not modify any of these properties when an application
#  using this configuration file has been installed as a service.
#  Please uninstall the service before modifying this section.
#  The service can then be reinstalled.

# Name of the service
wrapper.name=springboot

# Display name of the service
wrapper.displayname=SpringBoot

# Description of the service
wrapper.description=SpringBoot Server

# Service dependencies.  Add dependencies as needed starting from 1
wrapper.ntservice.dependency.1=

# Mode in which the service is installed.
#  AUTO_START, DELAY_START (Requires Standard Edition) or DEMAND_START
wrapper.ntservice.starttype=AUTO_START

# Account to use when running the service.
#  The default blank value will use LocalSystem, which is highly privileged
#  account on Windows. Please read the documentation page for this property to
#  learn about other account types that can be used.
wrapper.ntservice.account=

# Allow the current user to perform certain actions without being prompted for
#  administrator credentials. (Requires Professional Edition)
#wrapper.ntservice.permissions.1.account=CURRENT_USER
#wrapper.ntservice.permissions.1.allow=START, STOP, PAUSE_RESUME

While they are not required for this simple springboot jar, the above configuration file includes application parameters (wrapper.app.parameter.2 and wrapper.app.parameter.3) to specify the location of external configuration files and logging configuration:

  • --spring.config.location specifies the location of an optional application.properties file.

  • --logging.config specifies the location of a logback-spring.xml file.

As an example, please create the following conf/logback-spring.xml file: 

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>

    <property name="LOG_PATH" value="${LOG_PATH:-../logs}"/>
    <property name="LOG_FILE" value="${LOG_FILE:-sbapp}"/>

    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${LOG_PATH}/${LOG_FILE}.log</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>${LOG_PATH}/${LOG_FILE}.%d{yyyy-MM-dd}.%i.log</fileNamePattern>
            <maxFileSize>50MB</maxFileSize>
            <maxHistory>30</maxHistory>
            <totalSizeCap>2GB</totalSizeCap>
        </rollingPolicy>
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <root level="INFO">
        <appender-ref ref="FILE"/>
    </root>
</configuration>

NOTE

If you are using the Standard or Professional Edition, then a default 15 minute license will have been copied as etc/wrapper-license.conf. You will need to update with a trial, server, or development license to run for longer than that.

Running

To run within a console:

  • Execute: bin/service.bat console

To run as a Windows Service:

  • Install the service with: bin/service.bat install

  • Then start the service with: bin/service.bat start

  • Stop the service with: bin/service.bat stop

  • Uninstall the service with: bin/service.bat remove

For a list of available commands:

  • Run: bin/service.bat

Follow-Up Questions

If you are a SpringBoot power user and have suggestions for improving this document, please let us know at support@tanukisoftware.com.