Deploy Scala and Play Applications to Heroku from Jenkins CI

Last updated 24 August 2016

In addition to Git deployment, Heroku supports direct deployment of prepackaged standalone web applications using the Platform API.

Deploying a prepackaged Scala, Play or sbt application can be done from the command line, but most Scala developers will want to build and run tests from a stable and isolated environment – such as a CI server like Jenkins. In this article, you’ll learn how to configure Jenkins to automatically build an sbt project and deploy it to Heroku.

Creating a Scala application

To begin, we’ll need a simple Scala or Play web application built with sbt. You can use a project of your own, or start with a template by forking the heroku-jenkins-scala-example repository on GitHub. This project contains a simple build.sbt and a single service. Once the project is forked, clone it to your local machine with git.

Next, create a Heroku application for the project. Install the Heroku CLI and run the create command with the -n flag, which will prevent it from adding a Git remote.

$ heroku create
Creating obscure-sierra-7788... done, stack is cedar-14
http://obscure-sierra-7788.herokuapp.com/ | git@heroku.com:obscure-sierra-7788.git

Remember the name Heroku assigns to your application (in this case obscure-sierra-7788), we’ll need it in a moment.

Adding the Heroku sbt plugin

The Heroku sbt plugin adds a deployHeroku task to your application. This mechanism for deployment does not rely on pushing to a remote Git repository, but instead builds an archive of your application locally, and pushes it to the Heroku server using the Platform API.

To use the plugin, add the following code to your project/plugins.sbt file:

addSbtPlugin("com.heroku" % "sbt-heroku" % "1.0.1")

If you’re not using Play, then you’ll also need to add the sbt-native-packager plugin to this file. It provides a stage task, which is required for packaging your application.

Next, add something like this to your build.sbt, but replace “obscure-sierra-7788” with the name of the application you created a moment ago.

herokuAppName in Compile := "obscure-sierra-7788"

Now we’re ready to deploy! Run the following command:

$ sbt stage deployHeroku
...
[info] -----> Packaging application...
[info]        - app: obscure-sierra-7788
[info]        - including: target/universal/stage/
[info] -----> Creating build...
[info]        - file: target/heroku/slug.tgz
[info]        - size: 30MB
[info] -----> Uploading slug... (100%)
[info]        - success
[info] -----> Deploying...
[info] remote:
[info] remote: -----> Fetching custom tar buildpack... done
[info] remote: -----> JVM Common app detected
[info] remote: -----> Installing OpenJDK 1.8... done
[info] remote: -----> Discovering process types
[info] remote:        Procfile declares types -> console, web
[info] remote:
[info] remote: -----> Compressing... done, 78.9MB
[info] remote: -----> Launching... done, v6
[info] remote:        https://obscure-sierra-7788.herokuapp.com/ deployed to Heroku
[info] remote:
[info] -----> Done
[success] Total time: 90 s, completed Aug 29, 2014 3:36:43 PM

Your application will now be running on heroku. You can open it with this command:

$ heroku open -a obscure-sierra-7788

Before we move on, commit all of your changes and push them up to your GitHub repository like so:

$ git commit -am "added heroku plugin"
$ git push origin master

You can use the sbt plugin to deploy just as you might use git push with the repository based deployment strategy. But the plugin is an excellent fit with a CI server.

Creating a Jenkins instance on CloudBees

CloudBees, the primary maintainer of the Jenkins project, provides a free trial of its hosted Jenkins service. Browse to the CloudBees website and create an account. Once you’ve logged in, create a new DEV@Cloud build, which will provision a Jenkins instance for you.

Then from the Jenkins dashboard, create a new “free-style software project” as described in the CloudBees getting started documentation. Give the project a name, and then configure it to use the GitHub repository you created earlier.

Next, add a new build step to the configuration. Choose “Execute shell”, and in the Command text box, put the following statements:

curl -s https://raw.githubusercontent.com/paulp/sbt-extras/master/sbt > ~/bin/sbt \
  && chmod 0755 ~/bin/sbt

~/bin/sbt clean stage deployHeroku

The first command installs the sbt-extras tool, which will handle downloading and installing the correct version of sbt. The second command builds and deploys your application.

Save the project configuration by clicking the “Save” button. Then browse to the Jenkins dashboard again and choose Manage Jenkins -> Configure System. Under the “Global properties” section, add a new environment variable with the name HEROKU_API_KEY and use your API token as the value. You can get this token by running the following command on your local machine:

$ heroku auth:token

Save the system configuration by clicking the “Save” button. Then from the dashboard, select the menu next to the name of your project, and choose “Build Now”. After some time, Jenkins will run the build and deploy your app to Heroku again. You can view the details of the release with this command:

$ heroku releases -a obscure-sierra-7788

Deploying in this way is ideal for applications that want to run a large number of tests prior to sending the binaries into a running environment. It’s also great for applications that have a large number of dependencies, which cause a timeout during the dependency resolution phase of the build.

For more information on configuring and using Jenkins, see the Jenkins documentation and wiki. For more information on using Jenkins with CloudBees, see the CloudBees documentation.