This section describes where and how to configure different kind of paths settings.
-This table gives you a quick overview of the setting and the scope you should use. -Paths which do not begin with a / are relative to the universal directory. -The scopes are ordered from general to specific, so a more specific one will override -the generic one. Only the listed scopes for a setting a relevant. Any changes in other -scopes will have no effect!
-| output path | -scopes | -archetype | -comment | -
|---|---|---|---|
| lib | -all | -JavaApp | -- |
| conf | -all | -JavaApp | -- |
| bin/<executableScriptName> | -Global | -JavaApp | -- |
| bin/<executableScriptName>.bat | -Global | -JavaApp | -- |
| bin/<executableScriptName> | -Global | -- | Entrypoint DockerPlugin | -
| <defaultLinuxInstallationLocation>/<packageName> | -Linux, Debian, Rpm | -JavaApp | -- |
| <defaultLinuxLogLocation>/<packageName> | -Linux | -JavaServerApplication | -- |
| logs | -Linux | -JavaServerApplication | -Symlink | -
| /etc/default/<packageName> | -Linux | -JavaServerApplication | -- |
| /var/run/<packageName> | -Linux | -JavaServerApplication | -- |
| /etc/init.d/<packageName> | -Linux, Debian, Rpm | -JavaServerApplication | -For SystemV | -
| /etc/init/<packageName> | -Linux, Debian, Rpm | -JavaServerApplication | -For Upstart | -
| /usr/lib/systemd/system/<packageName>.service | -Linux, Debian, Rpm | -JavaServerApplication | -For Systemd | -
| <defaultLinuxInstallLocation> | -Docker | -- | Installation path inside the container | -
These settings configure the path behaviour
----
-- name
-- Use for the normal jar generation process
-- packageName
-- Defaults to normalizedName. Can be override in different scopes
-- executableScriptName
-- Defaults to normalizedName. Sets the name of the executable starter script
-- defaultLinuxInstallationLocation
-- Defaults to /usr/share/. Used to determine the installation path for for linux packages (rpm, debian)
-- defaultLinuxLogLocation
-- Defaults to /var/log/. Used to determine the log path for linux packages (rpm, debian).
-
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:
-The native packager provides a direct hook into the generated scripts for JVM configuration. Let’s make use of this. First, add the following to the src/universal/conf/jvmopts file in the project
--DsomeProperty=true
-Now, if we run the stage task, we’ll see this file show up in the distribution
-$ sbt stage
-$ ls target/universal/stage
- bin/
- conf/
- lib/
-$ ls target/universal/stage/conf
- jvmopts
-By default, any file in the src/universal directory is packaged. This is a convenient way to include things like licenses, and readmes.
-Now, we need to modify the script templates to load this configuration. To do so, add the following -to build.sbt
-bashScriptConfigLocation := Some("${app_home}/../conf/jvmopts")
-Here, we define the configuration location for the BASH script too look for the conf/jvmopts file. Now, let’s run sbt stage and then execute the script in debug mode to see what command line it executes
-./target/universal/stage/bin/example-cli -d
- # Executing command line:
- java
- -Xms1024m
- -Xmx1024m
- -XX:MaxPermSize=256m
- -XX:ReservedCodeCacheSize=128m
- -DsomeProperty=true
- -cp
- /home/jsuereth/projects/sbt/sbt-native-packager/tutorial-example/target/universal/stage/lib/example-cli.example-cli-1.0.jar:/home/jsuereth/projects/sbt/sbt-native-packager/tutorial-example/target/universal/stage/lib/org.scala-lang.scala-library-2.10.3.jar:/home/jsuereth/projects/sbt/sbt-native-packager/tutorial-example/target/universal/stage/lib/com.typesafe.config-1.2.0.jar
- TestApp
-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.
-Now that we have ability to configure the JVM, let’s add in a more robust method of customizing the applciation. We’ll be using the Typesafe Config library for this purpose.
-First, let’s add it as a dependency in build.sbt
-libraryDependencies += "com.typesafe" % "config" % "1.2.0"
-Next, let’s create the configuration file itself. Add the following to src/universal/conf/app.config
-example {
- greeting = "Hello, World!"
-}
-Now, we need a means of telling the typesafe config library where to find our configuration. The library supports -a JVM property “config.file” which it will use to look for configuration. Let’s expose this file -in the startup BASH script. To do so, add the following to build.sbt
-bashScriptExtraDefines += """addJava "-Dconfig.file=${app_home}/../conf/app.config""""
-This line modifies the generated BASH script to add the JVM options the location of the application configuration on disk. Now, let’s modify the application (src/main/scala/TestApp.scala) to read this configuration
-import com.typesafe.config.ConfigFactory
-
-object TestApp extends App {
- val config = ConfigFactory.load()
- println(config.getString("example.greeting"))
-}
-Now, let’s try it out on the command line
-$ sbt stage
-$ ./target/universal/stage/bin/example-cli
-Hello, World!
-Finally, let’s see what this configuration looks like in a linux distribution. Let’s run the debian packaging again
-$ sbt debian:packageBin
-The resulting structure is the following
-/usr/
- share/example-cli/
- conf/
- app.config
- jvmopts
- bin/
- example-cli
- lib/
- example-cli.example-cli-1.0.jar
- org.scala-lang.scala-library-2.10.3.jar
- bin/
- example-cli -> ../share/example-cli/bin/example-cli
-/etc/
- example-cli -> /usr/share/example-cli/conf
-Here, we can see that the entire conf directory for the application is exposed on /etc as is standard for other linux applications. By convention, all files in the universal conf directory are marked as configuration files when packaged, allowing users to modify them.
-While we just covered how to do configuration for linux/mac, windows offers some subtle differences.
-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. The path is hardcoded, as well to:
-<install directory>/@@APP_ENV_NAME@@_config.txt
-where @@APP_ENV_NAME@@ is replaced with an environment friendly name for your app. In this example, that would be: EXAMPLE_CLI.
-We can provide a configuration for JVM options on windows by creating a src/universal/EXAMPLE_CLI_config.txt file with the following contents
--Xmx512M
--Xms128M
-This will add each line of the file as arguments to the JVM when running your application.
-Now, if we want to add the typesafe config library again, we need to write the config.file property into the JVM options again.
-One means of doing this is hooking the batScriptExtraDefines key. This allows us to insert various BAT settings/commands into the script. Let’s use this to hook the config file location, using the other variables in the BASH script. Modify your build.sbt as follows
-batScriptExtraDefines += """set _JAVA_OPTS=%_JAVA_OPTS% -Dconfig.file=%EXAMPLE_CLI_HOME%\\conf\\app.config"""
-Now, the windows version will also load the configuration from the conf/ directory of the package.
-As you read earlier 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 Typesage config file above. For more complex -scripts you can also inject a seperate file managed in your source tree or resource directory:
-bashScriptExtraDefines ++= IO.readLines(baseDirectory.value / "scripts" / "extra.sh")
-This will add the contents of /scripts/extra.sh 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 linex to the start-script.
-Next, let’s add some generated files.
-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.
-The easiest way to add functionality to the default script is by adding bashScriptExtraDefines as described -in adding configuration for applications. Customizing the bash -script will effect all platform-specific builds. The server archetype provides a further level of customization for -specific System Loaders and Package types. These template file are described in -configuring servers.
-In order to override full templates, like the default bash script, create a file in src/templates/bash-template
-#!/usr/bin/env bash
-
-realpath() {
- # TODO - The original bash template has a robust mechanism to find the true
- # path to your application, following multiple symlinks.
- #
-}
-
-addJava() {
- # Here we override the original templates addJava method to do nothing,
- # since this was how we were adding configuration before.
-}
-
-declare -r real_script_path="$(realpath "$0")"
-
-# We have to provide an app_home for the default bash declarations to work.
- declare -r app_home="$(realpath "$(dirname "$real_script_path")")"
-
- # The auto-generated classpath relies on this variable existing
- # and pointing at the lib directory.
-declare -r lib_dir="$(realpath "${app_home}/../lib")"
-
-# This line tells the native packager template engine to inject
-# all of its settings into this spot in the bash file.
-${{template_declares}}
-
-# Here we make use of two of the injected settings for the bash file:
-# * app_classpath - represents the full list of JARs for this applciation.
-# * app_mainclass - represents the class with a main method we should call.
-exec java -cp $app_classpath $app_mainclass $@
-Similarly the windows BAT template can be overridden by placing a new template in src/templates/bat-template
-@REM A bat starter script
-@echo off
-
-@REM Here we need to set up a "home" variable for our classpath.
-@REM The APP_ENV_NAME variable is replaced by the packager template engine
-@REM with an "environment variable friendly" name for the app.
-if "%@@APP_ENV_NAME@@_HOME%"=="" set "@@APP_ENV_NAME@@_HOME=%~dp0\\.."
-set "APP_LIB_DIR=%@@APP_ENV_NAME@@_HOME%\lib\"
-
-@REM - This tells the template engine to inject any custom defines into our bat file here.
-@@APP_DEFINES@@
-
-@REM - Here we use the provided APP_CLASSPATH and APP_MAIN_CLASS parameters
-java -cp "%APP_CLASSPATH%" %APP_MAIN_CLASS% %*
-While we just replaced the default templates with simpler templates, this should really only be done if:
-In general, the templates are intended to provide enough utility that customization is only necessary for truly custom scripts.
-Next, let’s look at how to document the application.
-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:
-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 dependend, each OS gets section.
-Create src/templates/etc-default with the following template
-# Available replacements
-# ------------------------------------------------
-# ${{author}} debian author
-# ${{descr}} debian 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 -Xmx and -Xms in Megabyte
-# -mem 1024
-
-# Setting -X directly (-J is stripped)
-# -J-X
-# -J-Xmx1024
-
-# Add additional jvm parameters
-# -Dkey=val
-
-# For play applications you may set
-# -Dpidfile.path=/var/run/${{app_name}}/play.pid
-
-# 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 swalloing when
-# using a reserved parameter. See #184
-# -d -- -d
-The file will be installed to /etc/default/<normalizedName> and read from there -by the startscript.
-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.
-Support planned for 0.8.0
-A list of very small configuration settings can be found at sbt-native-packager-examples
---
In addition to adding configuration settings it’s possible to override parts of the start/stop scripts -used in the java_server archetype or replace entire templates. The next section on -how to override start templates explains this feature.
-Some scripts are covered in the standard application type. Read more on Template Customization and Overrides. -For the java_server package lifecycle scripts are customized to provide the following additional features
-For this purpose sbt-native-packager ships with some predefined templates. These can be -overriden with different techniques, depending on the packaging system.
-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 puts all scripts into one file. To override or append settings to your -scriptlets use these settings:
----
-- rpmPre
-- %pre scriptlet
-- rpmPost
-- %post scriptlet
-- rpmPosttrans
-- %posttrans scriptlet
-- rpmPreun
-- “%preun scriptlet”
-- rpmPostun
-- %postun scriptlet
-- rpmVerifyscript
-- %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 rpmScriptsDirectory (by default src/rpm/scriptlets).
----
-- rpmScriptsDirectory
-- By default to src/rpm/scriptlets. Place your templates here.
-
Available templates are
---post-rpm -pre-rpm -postun-rpm -preun-rpm
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"
-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
--This is a list of values you can access in your templates
---${{author}} -${{descr}} -${{exec}} -${{chdir}} -${{retries}} -${{retryTimeout}} -${{app_name}} -${{daemon_user}} -${{daemon_group}} -
The sbt-native-packager is an sbt plugin for bundling your server for a variety of platforms.
-Note: Please follow the Installation instructions for how to set it up on a project.
-In the Application Packaging section we described how to build and -customize settings related to the application. Sbt-Native-Packager provides a further level for servers -which define how applications are installed and initialized for various platforms. -be customized for specific platforms. While it provides -some basic abstractions around packaging, it also allows you to dig down into the nuts and bolts of each platform as -neeeded to generate the best package possible.
-Platforms are tied to both package managers (Rpm, Debian) and Service Managers (System V, Upstart, SystemD). By -default the native packager will configure a service manager to run the daemon process. The available -configurations are:
-| Platform | -Service Manager | -Working | -
|---|---|---|
| Ubuntu | -Upstart (Default) | -X | -
| Ubuntu | -System V | -X | -
| CentOS | -System V (Default) | -X | -
| CentOS 6.5 | -Upstart | -X | -
| Fedora | -System V (Default) | -X | -
| Fedora | -systemd | -experimental | -
| Windows | -Windows Services | -- |
It is possible to change the default Service Manager for a given platform by specifying a ServerLoader. To use -Upstart for an Rpm package simply:
-serverLoading in Rpm := ServerLoader.Upstart
-As a side note Fedora/RHEL/Centos family of linux -specifies Default requiretty in its /etc/sudoers -file. This prevents the default Upstart script from working -correctly as it uses sudo to run the application -as the daemonUser . Simply disable requiretty -to use Upstart or modify the Upstart template.
-Sbt Native Packager leverages templating to customize various start/stop scripts and pre/post install tasks. -The templating reference describes this functionality in-depth. -As an example, to alter the loader-functions which manage the specific start and stop process commands -for SystemLoaders you can to the linuxScriptReplacements map:
-linuxScriptReplacements += "loader-functions" -> TemplateWriter.generateScript(getClass.getResource("/custom-loader-functions"), Nil)
-which will add the following resource file to use start/stop instead of initctl in the post install script:
-startService() {
- app_name=$1
- start $app_name
-}
-
-stopService() {
- app_name=$1
- stop $app_name
-}
-The debian and redhat pages have further information on overriding distribution scpecific actions.
-There is also experimental systemd support for Fedora release 20 (Heisenbug). You can use the `Systemd` server loader:
-serverLoading in Rpm:= ServerLoader.Systemd
-There is only partial systemd support in Ubuntu 14.04 LTS which prevents sbt-native-packager systemd from working correctly on -Ubuntu.
-A server project extends the basic java_application with some server specific features, -which are currently on
-Next, let’s get started with simple application
-appUser for services as it represents a security risk.
+ Packaging format for Debian based systems like Ubuntu
+debian:packageBin+ Debian Plugin » +
Packaging format for Redhat based systems like RHEL or CentOS.
+rpm:packageBin+ Rpm Plugin » +
Package your application in a docker container.
+docker:publishLocal+ Docker Plugin » +
Packaging format for all systems supporting zip.
+universal:packageBin+ Universal Plugin » +
Packaging format for all systems supporting tar.
+universal:packageZipTarball+ Universal Plugin » +
Packaging format for all systems supporting xz.
+universal:packageXzTarball+ Universal Plugin » +
Creates a standalone package with an executable bash/bat script.
enablePlugins(JavaAppPackaging)+ Learn more » +
Creates a standalone package with an executabl bash/bat script and additional configuration and autostart.
+enablePlugins(JavaServerAppPackaging)+ Learn more » +
Like a the Java Application archetype, but instantiates and runs a subclass of
+ Bootable
enablePlugins(AkkaAppPackaging)+ Learn more » +
This sbt plugin provides you with everything you need to package your application. + No matter if you want to build a simple standalone application or a server application. + The JVM let's you run anywhere. SBT Native Packager let's you deploy everywhere!
+ +Add the plugin to your plugins.sbt. If you use sbt 0.13.5 + or higher the you have just one line to add to your build.sbt:
+enablePlugins(SbtNativePackager)+
We provide a set of plugins. One for each supported format and for each archetype.
+ Just select the one you want to use and all other plugins you require are loaded
+ automatically.
For common use cases we create so called Archetypes. For a standalone + application enabling is as simple + simple as
+enablePlugins(JavaAppPackaging)+
+ The most common archtypes
+ are JavaAppPackaging and JavaServerAppPackaging.
+ Each archetype adds possible new settings which you can adapt to your need.
SBT Native Packager comes with a rich set of packaging formats including + zip, tar.gz, debian, rpm, msi and docker. + It's as easy as:
+sbt debian:packageBin+
An archetype doesn't cover what you need? No problem. SBT Native Packager i + build on top of some simple principles and you can customize it in many ways. + Adding a custom packaging format or some special files.
+ +This is a set FAQ composed on a single page.
+This section describes where and how to configure different kind of paths settings.
+This table gives you a quick overview of the setting and the scope you should use. +Paths which do not begin with a / are relative to the universal directory. +The scopes are ordered from general to specific, so a more specific one will override +the generic one. Only the listed scopes for a setting a relevant. Any changes in other +scopes will have no effect!
+| output path | +scopes | +archetype | +comment | +
|---|---|---|---|
| lib | +all | +JavaApp | ++ |
| conf | +all | +JavaApp | ++ |
| bin/<executableScriptName> | +Global | +JavaApp | ++ |
| bin/<executableScriptName>.bat | +Global | +JavaApp | ++ |
| bin/<executableScriptName> | +Global | ++ | Entrypoint DockerPlugin | +
| <defaultLinuxInstallationLocation>/<packageName> | +Linux, Debian, Rpm | +JavaApp | ++ |
| <defaultLinuxLogLocation>/<packageName> | +Linux | +JavaServerApplication | ++ |
| logs | +Linux | +JavaServerApplication | +Symlink | +
| /etc/default/<packageName> | +Linux | +JavaServerApplication | ++ |
| /var/run/<packageName> | +Linux | +JavaServerApplication | ++ |
| /etc/init.d/<packageName> | +Linux, Debian, Rpm | +JavaServerApplication | +For SystemV | +
| /etc/init/<packageName> | +Linux, Debian, Rpm | +JavaServerApplication | +For Upstart | +
| /usr/lib/systemd/system/<packageName>.service | +Linux, Debian, Rpm | +JavaServerApplication | +For Systemd | +
| <defaultLinuxInstallLocation> | +Docker | ++ | Installation path inside the container | +
These settings configure the path behaviour
++++
+- name
+- Use for the normal jar generation process
+- packageName
+- Defaults to normalizedName. Can be override in different scopes
+- executableScriptName
+- Defaults to normalizedName. Sets the name of the executable starter script
+- defaultLinuxInstallationLocation
+- Defaults to /usr/share/. Used to determine the installation path for for linux packages (rpm, debian)
+- defaultLinuxLogLocation
+- Defaults to /var/log/. Used to determine the log path for linux packages (rpm, debian).
+
You can override the default template used to generate any of the scripts in +any archetype. Listed below are the overridable files and variables that +you can use when generating scripts.
+Creating a file here will override the default template used to +generate the .bat script for windows distributions.
+Syntax
+@@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.
+You can define addiitonal variable definitions using batScriptExtraDefines.
+Creating a file here will override the default template used to +generate the BASH start script found in bin/<application> in the +universal distribution
+Syntax
+${{template_declares}} - Will be replaced with a series of declare <var> +lines based on the bashScriptDefines key. You can add more defines to +the bashScriptExtraDefines that will be used in addition to the default set:
+Creating a file here will override either the init.d startup script or +the upstart start script. It will either be located at +/etc/init/<application> or /etc/init.d/<application> depending on which +serverLoader is being used.
+Syntax
+You can use ${{variable_name}} to reference variables when writing your scirpt. The default set of variables is:
+Creating a file here will override the /etc/default/<application> template +used when SystemV is the server loader.
+Application packaging focuses on how your application is launched (via a bash or bat script), how dependencies +are managed and how configuration and other auxillary files are included in the final distributable. The JavaAppPackaging archetype +provides a default application structure and executable scripts to launch your application.
+Additionally there is Server Packaging which provides platform-specific +functionality for installing your application in server environments. You can customize specific debian and rpm packaging +for a variety of platforms and init service loaders including Upstart, System V and SystemD (experimental).
+The JavaAppPackaging archetype contains the following features.
+Version 1.0 or higher with sbt 0.13.5 and and higher
+enablePlugins(JavaAppPackaging)
+Version 0.8 or lower
+import com.typesafe.sbt.SbtNativePackager._
+import NativePackagerKeys._
+
+packageArchetype.java_app
+You can customize the bash/bat scripts in different ways. This is explained in +the Customize section. The application structure is customizable +via the standard mappings, which is described in the Universal Plugin Section.
+