Documentation

You are viewing the documentation for the 2.3.x release series. The latest stable release series is 3.0.x.

§Creating a standalone version of your application

§Using the dist task

The simplest way to deploy a Play application is to retrieve the source (typically via a git workflow) on the server and to use either activator start or activator stage to start it in place.

However, you sometimes need to build a binary version of your application and deploy it to the server without any dependency on Play itself. You can do this with the dist task.

In the Play console, simply type dist:

[my-first-app] $ dist

This produces a ZIP file containing all JAR files needed to run your application in the target/universal folder of your application. Alternatively you can run activator dist directly from your OS shell prompt, which does the same thing:

$ activator dist

For Windows users a start script will be produced with a .bat file extension. Use this file when running a Play application on Windows.

For Unix users, zip files do not retain Unix file permissions so when the file is expanded the start script will be required to be set as an executable:

$ chmod +x /path/to/bin/<project-name>

Alternatively a tar.gz file can be produced instead. Tar files retain permissions. Invoke the universal:package-zip-tarball task instead of the dist task:

activator universal:package-zip-tarball

By default, the dist task will include the API documentation in the generated package. If this is not necessary, it can be avoided by including this line in build.sbt:

doc in Compile <<= target.map(_ / "none")

For builds with sub-projects, the statement above has to be applied to all sub-project definitions.

§The Native Packager

Play uses the SBT Native Packager plugin. The native packager plugin declares the dist task to create a zip file. Invoking the dist task is directly equivalent to invoking the following:

$ activator universal:package-bin

Many other types of archive can be generated including:

Please consult the documentation on the native packager for more information.

§Build a server distribution

The sbt-native-packager plugins provides and java_server archetype which enables the following features

A full documentation can be found in the documentation.

The java_server archetype is enabled by default, but depending on which package you want to build you have to add a few settings.

§Minimal Debian settings

import com.typesafe.sbt.SbtNativePackager._
import NativePackagerKeys._

maintainer in Linux := "First Lastname <[email protected]>"

packageSummary in Linux := "My custom package summary"

packageDescription := "My longer package description"

Build your package with

activator debian:packageBin

§Minimal RPM settings

import com.typesafe.sbt.SbtNativePackager._
import NativePackagerKeys._

maintainer in Linux := "First Lastname <[email protected]>"

packageSummary in Linux := "My custom package summary"

packageDescription := "My longer package description"

rpmRelease := "1"

rpmVendor := "example.com"

rpmUrl := Some("http://github.com/example/server")

rpmLicense := Some("Apache v2")

activator rpm:packageBin

There will be some error logging. This is rpm logging on stderr instead of stdout !

§Play PID Configuration

Play manages its own PID, which is described in the Production configuration. In order to tell the startup script where to place the PID file put a file etc-default inside src/templates/ folder and add the following content

-Dpidfile.path=/var/run/${{app_name}}/play.pid
# Add all other startup settings here, too

For a full list of replacements take a closer look at the documentation.

§Publishing to a Maven (or Ivy) repository

You can also publish your application to a Maven repository. This publishes both the JAR file containing your application and the corresponding POM file.

You have to configure the repository you want to publish to, in your build.sbt file:

 publishTo := Some(
   "My resolver" at "https://mycompany.com/repo"
 ),
 
 credentials += Credentials(
   "Repo", "https://mycompany.com/repo", "admin", "admin123"
 )

Then in the Play console, use the publish task:

[my-first-app] $ publish

Check the sbt documentation to get more information about the resolvers and credentials definition.

§Using the SBT assembly plugin

Though not officially supported, the SBT assembly plugin may be used to package and run Play applications. This will produce one jar as an output artifact, and allow you to execute it directly using the java command.

To use this, first ensure you are using at least version 0.13.6 of sbt by updating the version in your project/build.properties file, then add a dependency on the plugin to your project/plugins.sbt file:

addSbtPlugin("com.eed3si9n" % "sbt-assembly" % "0.12.0")

Now add the following configuration to your build.sbt:

mainClass in assembly := Some("play.core.server.NettyServer")

fullClasspath in assembly += Attributed.blank(PlayKeys.playPackageAssets.value)

// Exclude commons-logging because it conflicts with the jcl-over-slf4j
libraryDependencies ~= { _ map {
  case m if m.organization == "com.typesafe.play" =>
    m.exclude("commons-logging", "commons-logging")
  case m => m
}}

// Take the first ServerWithStop because it's packaged into two jars
assemblyMergeStrategy in assembly := {
  case PathList("play", "core", "server", "ServerWithStop.class") => MergeStrategy.first
  case other => (assemblyMergeStrategy in assembly).value(other)
}

Now you can build the artifact by running activator assembly, and run your application by running:

$ java -jar target/scala-2.XX/<yourprojectname>-assembly-<version>.jar

You’ll need to substitute in the right project name, version and scala version, of course.

Next: Production configuration

Found an error in this documentation? The source code for this page can be found here. After reading the documentation guidelines, please feel free to contribute a pull request. Have questions or advice to share? Go to our community forums to start a conversation with the community.