Consider sbt-native-packager instead
The more general native-packager plugin may replace this one in the future: https://github.com/sbt/sbt-native-packager
The rough way to get a start script with sbt-native-packager, modulo any details of your app, is:
- add sbt-native-packager plugin to your project
- remove start-script-plugin
stagetask will now generate a script
- the sbt-native-packager-generated script looks at a
java_optsenv var but you cannot pass Java opts as parameters to the script as you could with
- the sbt-native-packager-generated script copies dependency jars into
target/, so you don't need the Ivy cache
Many were using sbt-start-script with Heroku, sbt-native-packager has two tricky things on Heroku right now:
- Heroku sets
java_opts. See sbt/sbt-native-packager#47 and sbt/sbt-native-packager#48 ... for now you have to manually configure
java_optsand not specify memory options, or hack sbt-native-packager.
- You need to hack the build pack to drop the Ivy cache, or your slug will be bloated or even exceed the max size.
Also of course you have to change your
Procfile for the new name of the script.
About this plugin (sbt-start-script)
This plugin allows you to generate a script
target/start for a
project. The script will run the project "in-place" (without having
to build a package first).
target/start script is similar to
sbt run but it doesn't rely
sbt run is not recommended for production use because it
keeps SBT itself in-memory.
target/start is intended to run an
app in production.
The plugin adds a task
start-script which generates
It also adds a
stage task, aliased to the
stage by convention performs any tasks needed to prepare an app to
be run in-place. Other plugins that use a different approach to
prepare an app to run could define
stage as well, while
start-script is specific to this plugin.
target/start script must be run from the root build directory
(note: NOT the root project directory). This allows inter-project
dependencies within your build to work properly.
To use the plugin with SBT 0.12.x:
addSbtPlugin("com.typesafe.sbt" % "sbt-start-script" % "0.9.0")
You can place that code in
~/.sbt/plugins/build.sbt to install the
plugin globally, or in
install the plugin for your project.
To use with SBT 0.13.x:
addSbtPlugin("com.typesafe.sbt" % "sbt-start-script" % "0.10.0")
Note: the global directory for 0.13.x is
~/.sbt/0.13 instead of
If you install the plugin globally, it will add a command
add-start-script-tasks to every project using SBT. You can run this
command to add the tasks from the plugin, such as
start-script task won't exist until you
If you incorporate the plugin into your project, then you'll want to
explicitly add the settings from the plugin, such as the
start-script task, to your project. In this case there's no need to
add-start-script-tasks since you'll already add them in your
Here's how you add the settings from the plugin in a
import com.typesafe.sbt.SbtStartScript seq(SbtStartScript.startScriptForClassesSettings: _*)
In an SBT "full configuration" you would do something like:
settings = SbtStartScript.startScriptForClassesSettings
You have to choose which settings to add from these options:
startScriptForClassesSettings(the script will run from .class files)
startScriptForJarSettings(the script will run from .jar file from 'package')
startScriptForWarSettings(the script will run a .war with Jetty)
https://github.com/siasia/xsbt-web-plugin/ to provide the
If you have an aggregate project, you may want a
stage task even
though there's nothing to run, just so it will recurse into sub-projects.
One way to get a
stage task that does nothing is:
SbtStartScript.stage in Compile := Unit
which sets the
stage key to
Note that all the keys (except
stage) are in the
SbtStartScript.StartScriptKeys object, so the scala version of
start-script key is
SbtStartScript.StartScriptKeys.startScript. This is the standard
convention for sbt plugins. Do an
import SbtStartScript.StartScriptKeys._ if you want all the keys
unprefixed in your scope. Then, if you want to change a setting, you
can simply reference the key directly in your `build.sbt'.
For example, to change the filename of the generated script to
something other than
target/start (which is controlled by the
SbtStartScript.StartScriptKeys.startScriptName), add the
build.sbt after the above import statement:
startScriptName <<= target / "run"
Migration from earlier versions of xsbt-start-script-plugin
After 0.5.2, the plugin and its APIs were renamed to use consistent conventions (matching other plugins). The renamings were:
- the plugin itself is now
xsbt-start-script-plugin; update this in your
- the Maven group and Java package are now
com.typesafe.startscript; update this in your
plugins.sbtand in your build files
- the plugin object is now
StartScriptPlugin, update this in your build files
- if you used any keys directly, they are now inside a nested
StartScriptKeysso for example rather than writing
startScriptFileyou would write
StartScriptKeys.startScriptFileor you need to
StartScriptKeys.startScriptFiledid not match the string name of that settings
start-script-nameso now you should use
sbt-start-script is open source software licensed under the Apache 2.0 License.
Contributions via GitHub pull requests are gladly accepted from their original author. Before sending the pull request, please agree to the Contributor License Agreement at http://typesafe.com/contribute/cla (it takes 30 seconds; you use your GitHub account to sign the agreement).