The application structure is customizable via the standard mappings, which is described in the Universal Plugin Section.

Application and runtime configuration

There are generally two types of configurations:

  • Configuring the JVM and the process
  • Configuring the application itself

You have three options to define your runtime and application configurations.

Via build.sbt

First, you can specify your options via the build.sbt.

javaOptions in Universal ++= Seq(
    // -J params will be added as jvm parameters

    // others will be added as app parameters

    // you can access any build setting/task here

For the -X settings you need to add a suffix -J so the start script will recognize these as vm config parameters.

Via Application.ini

The second option is to create src/universal/conf/application.ini with the following template (For Windows-user: Create src/universal/<APP_ENV_NAME>_config.txt instead of the application.ini, it is expected that way by the BAT-template. Inside the <App_ENV_NAME>_config.txt the jvm-options are expected like in the command-line (e.g. -Xms2G -Xmx3G) without an leading J)

# Setting -X directly (-J is stripped)
# -J-X

# Add additional jvm parameters

# Turn on JVM debugging, open at the given port
# -jvm-debug <port>

# Don't run the java version check
# -no-version-check

# enabling debug and sending -d as app argument
# the '--' prevents app-parameter swallowing when
# using a reserved parameter. See #184
# -d -- -d

The file will be installed to ${app_home}/conf/application.ini and read from there by the startscript. You can use # for comments and new lines as you like. This file currently doesn’t has any variable substitution. We recommend using the build.sbt if you need any information from your build.

The configuration file for bash scripts takes arguments for the BASH file on each line, and allows comments which start with the # character. Essentially, this provides a set of default arguments when calling the script.

By default, any file in the src/universal directory is packaged. This is a convenient way to include things like licenses, and readmes.

If you don’t like application.ini as a name, you can change this in the build.sbt. The default configuration looks like this

bashScriptConfigLocation := Some("${app_home}/../conf/application.ini")

BashScript defines

The last option is to use the bashScriptExtraDefines. Generally you can add arbitrary bash commands here, but for configurations you have two methods to add jvm and app parameters.

// add jvm parameter for typesafe config
bashScriptExtraDefines += """addJava "-Dconfig.file=${app_home}/../conf/app.config""""
// add application parameter
bashScriptExtraDefines += """addApp "--port=8080"""


Will be replaced with a series of declare <var> lines based on the bashScriptDefines key. These variables are predefined: * app_mainclass - The main class entry point for the application. * app_classpath - The complete classpath for the application (in order).

BatScript defines

First, while the BASH file allows you to configure where to load JVM options and default arguments, in windows we can only configure JVM options.

 // add jvm parameter for typesafe config
batScriptExtraDefines += """set _JAVA_OPTS=%_JAVA_OPTS% -Dconfig.file=%EXAMPLE_CLI_HOME%\\conf\\app.config"""


@@APP_ENV_NAME@@ will be replaced with the script friendly name of your package.

@@APP_NAME@@ will be replaced with user friendly name of your package.

@APP_DEFINES@@ will be replaced with a set of variable definitions, like APP_MAIN_CLASS, APP_MAIN_CLASS.

Start script customizations

While the native packager tries to provide robust BASH/BAT scripts for your applications, they may not always be enough. The native packager provides a mechanism where the template used to create each script can be customized or directly overridden.

Bash and Bat script extra defines

For the bat and bash script are separated settings available to add arbitrary code to the start script. See BashScript defines and BatScript defines for details.

The bashScriptExtraDefines sequence allows you to add new lines to the default bash script used to start the application. This is useful when you need a setting which isn’t mean for the command-line parameter list passed to the java process. The lines added to bashScriptExtraDefines are placed near the end of the script and have access to a number of utility bash functions (e.g. addJava, addApp, addResidual, addDebugger). You can add lines to this script as we did for the Typesafe config file above. For more complex scripts you can also inject a separate file managed in your source tree or resource directory:

bashScriptExtraDefines ++= IO.readLines(baseDirectory.value / "scripts" / "")

This will add the contents of /scripts/ in the resource directory to the bash script. Note you should always concatenate lines to bashScriptExtraDefines as other stages in the pipeline may be include lines to the start-script.

Overriding Templates (Bash/Bat)


Replacing the default templates should really only be done if:

  1. There is a bug in one of the script templates you need to workaround
  2. There is a deficiency in the features of one of the templates you need to fix.

In general, the templates are intended to provide enough utility that customization is only necessary for truly custom scripts.

In order to override full templates, like the default bash script, you can create a file in src/templates/bash-template. Alternatively, you can use a different file location by setting bashScriptTemplateLocation. There are

Similarly the windows BAT template can be overridden by placing a new template in src/templates/bat-template. You can also use a different file location by setting batScriptTemplateLocation.