Application Configuration

After creating a package, the very next thing needed, usually, is the ability for users/ops to customize the application once it’s deployed. Let’s add some configuration to the newly deployed application.

There are generally two types of configurations:

  • Configuring the JVM and the process

  • Configuring the Application itself.

The server archetype provides you with a special feature to configure your application with a single file outside of customizing the bash or bat script for applications. As this file is OS dependent, each OS gets section.

Linux Configuration

There are different ways described in Customizing the Application and can be used the same way.

The server archetype adds an additional way with an etc-default file placed in src/templates, which currently only works for SystemV and systemd. The file gets sourced before the actual startscript is executed. The file will be installed to /etc/default/<normalizedName>

Example /etc/default/<normalizedName> for SystemV:

# Available replacements
# ------------------------------------------------
# ${{author}}           package author
# ${{descr}}            package description
# ${{exec}}             startup script name
# ${{chdir}}            app directory
# ${{retries}}          retries for startup
# ${{retryTimeout}}     retry timeout
# ${{app_name}}         normalized app name
# ${{daemon_user}}      daemon user
# -------------------------------------------------

# Setting JAVA_OPTS
# -----------------
JAVA_OPTS="-Dpidfile.path=/var/run/${{app_name}}/play.pid $JAVA_OPTS"

# For rpm/systemv you need to set the PIDFILE env variable as well
PIDFILE="/var/run/${{app_name}}/play.pid"

# export env vars for 3rd party libs
# ----------------------------------
COMPANY_API_KEY=123abc
export COMPANY_API_KEY

Daemon User and Group

Customize the daemon user and group for your application with the following settings.

// a different daemon user
Linux / daemonUser := "my-user"
// if there is an existing one you can specify the uid
Linux / daemonUserUid := Some("123")
// a different daemon group
Linux / daemonGroup := "my-group"
// if the group already exists you can specify the uid
Linux / daemonGroupGid := Some("1001")

Environment variables

The usual JAVA_OPTS can be used to override settings. This is a nice way to test different jvm settings with just restarting the jvm.

Windows Configuration

Support planned.

Systemloader Configuration

See the Systemloaders documentation on how to add a systemloader (e.g. SystemV, Systemd or Upstart) to your package.

Package Lifecycle Configuration

Some scripts are covered in the standard application type. Read more on Java Application Customization. For the java_server package lifecycle scripts are customized to provide the following additional features

  • Chowning directories and files correctly (if necessary)

  • Create/Delete users and groups according to your mapping

  • Register application at your init system

For this purpose sbt-native-packager ships with some predefined templates. These can be overridden with different techniques, depending on the packaging system.

Partially Replace Template Functionality

Most sbt-native-packager scripts are broken up into partial templates in the resources directory. You can override these default template snippets by adding to the linuxScriptReplacements map. As an example you can change the loader-functions which starts/stop services based on a certain `ServerLoader`:

linuxScriptReplacements += "loader-functions" -> TemplateWriter.generateScript(getClass.getResource("/custom-loader-functions"), Nil)

The custom-loader-functions file must declare the startService() and stopService() functions used in various service management scripts.

RPM Scriptlets

RPM puts all scripts into one file. To override or append settings to your scriptlets use Rpm / maintainerScripts or these ``RpmConstants._``s:

Pre

%pre scriptlet

Post

%post scriptlet

Pretrans

%pretrans scriptlet

Posttrans

%posttrans scriptlet

Preun

“%preun scriptlet”

Postun

%postun scriptlet

Verifyscript

%verifyscript scriptlet

If you want to have your files separated from the build definition use the default location for rpm scriptlets. To override default templates in a RPM build put the new scriptlets in the rpmScriptletsDirectory (by default src/rpm/scriptlets).

RpmConstants.Scriptlets

By default to src/rpm/scriptlets. Place your templates here.

Available templates are

post-rpm pre-rpm postun-rpm preun-rpm

The corresponding maintainer file names are:

pretrans post pre postun preun verifyscript posttrans

Override Postinst scriptlet

By default the post-rpm template only starts the service, but doesn’t register it.

service ${{app_name}} start

For CentOS we can do

chkconfig ${{app_name}} defaults
service ${{app_name}} start || echo "${{app_name}} could not be started. Try manually with service ${{app_name}} start"

For RHEL

update-rc.d ${{app_name}} defaults
service ${{app_name}} start || echo "${{app_name}} could not be started. Try manually with service ${{app_name}} start"

Debian Control Scripts

To override default templates in a Debian build put the new control files in the debianControlScriptsDirectory (by default src/debian/DEBIAN).

debianControlScriptsDirectory

By default to src/debian/DEBIAN. Place your templates here.

debianMakePreinstScript

creates or discovers the preinst script used by this project.

debianMakePrermScript

creates or discovers the prerm script used by this project.

debianMakePostinstScript

creates or discovers the postinst script used by this project.

debianMakePostrmScript

creates or discovers the postrm script used by this project.

Available templates are

postinst preinst postun preun

Linux Replacements

This is a list of values you can access in your templates

${{author}}
${{descr}}
${{exec}}
${{chdir}}
${{retries}}
${{retryTimeout}}
${{app_name}}
${{daemon_user}}
${{daemon_group}}

Attention

Every replacement corresponds to a single setting or task. For the linuxScriptReplacements you need to override the setting/task in the Linux scope. For example

Linux / daemonUser := "new-user"

overrides the daemon_user in the linuxScriptReplacements.

Example Configurations

A list of very small configuration settings can be found at sbt-native-packager-examples