24 Deploying to Heroku

Heroku is a scalable polyglot cloud application platform. It allows you to focus on writing applications in the language of your choice, and then easily deploy them to the cloud without having to manually manage servers, load balancing, log aggregation, etc. Heroku does not have, nor does it need, any special Ratpack support above its generic support for JVM applications. Heroku is a rich platform, with many elements such as Postgres, Redis, Memcache, RabbitMQ, New Relic, etc. It is a compelling option for serving Ratpack applications.

Deployments to Heroku are typically in source form. Deploying is as simple as performing a Git push at the end of your CI pipeline. Many popular cloud CI tools such as drone.io and Travis-CI (among others) have convenient support for pushing to Heroku.

It is recommended to read the Heroku Quickstart and Buildpack documentation if you are new to Heroku. The rest of this chapter outlines the requirements and necessary configuration for deploying Ratpack applications to Heroku.

24.1 Gradle based builds

Ratpack applications can be built by any build system, but the Ratpack team recommends Gradle. Heroku has native support for Gradle via the Gradle buildpack, which works well with the Ratpack Gradle plugins.

All Gradle projects should use the Gradle Wrapper. If the wrapper scripts are present in your project, Heroku will detect that your project is built with Gradle.

24.1.1 Building

The Gradle buildpack will invoke ./gradlew installDist -x test by default when it detects that Ratpack is being used. The installDist task is added by the Ratpack Gradle plugins (installApp prior to Gradle 2.3), and should work by default. This will build your application and install it into the directory build/install/«project name».

If you need to run a different task, you can add a stage task to your build.gradle. A typical stage task might look like this:

task stage {
  dependsOn clean, installDist
}

If a stage task is present, Heroku will run this instead of the default task.

24.1.1.1 Setting the project name

By default, Gradle uses the project’s directory name as the project’s name. In Heroku (and some CI servers), the project is built in a temporary directory with a randomly assigned name. To ensure that the project uses a consistent name, add a declaration to settings.gradle in the root of your project:

rootProject.name = "«project name»"

This is a good practice for any Gradle project.

24.1.2 Running (Procfile)

By default, Heroku will run the following script to start your app:

build/install/«project name»/bin/«project name»

You can customize this command by creating a Procfile in the root of your application and specifying the command that Heroku should use to start your application prefixed by web:.

24.1.3 Configuration

There are several ways to configure the environment for applications deployed to Heroku. You may want to use these mechanisms to set environment variables and/or JVM system properties to configure your application.

The application entry points that are used when using the ratpack and ratpack-groovy Gradle plugins support using JVM system properties to contribute to the ServerConfig (see the launching chapter chapter for more detail). The starter scripts created by the Ratpack Gradle plugins, support the standard JAVA_OPTS environment variable and an app specific «PROJECT_NAME»_OPTS environment variable. If your application name was foo-Bar, then the environment variable would be named FOO_BAR_OPTS.

One way to bring this all together is to launch your application via env:

web: env "FOO_BAR_OPTS=-Dapp.dbPassword=secret" build/install/«project name»/bin/«project name»

It is generally preferable to not use JAVA_OPTS as Heroku sets this to useful defaults for the platform.

Another approach is to use config vars. The benefit of setting the environment via the Procfile is that this information is in your versioned source tree. The benefit of using config vars is that they are only available to those with permissions to view/change them with Heroku. It is possible to combine both approaches by setting config vars for values that should be secret (like passwords) and referencing them in your Procfile.

web: env "FOO_BAR_OPTS=-Dapp.dbPassword=$SECRET_DB_PASSWORD" build/install/«project name»/bin/«project name»

Now it is easy to see which properties and environment variables are set in the source tree, but sensitive values are only visible via the Heroku management tools.

24.2 Other build tools and binary deployments

The Ratpack project does not provide any “official” integration with other build tools. However, it is quite possible to use whatever tool you like to build a Ratpack application for Heroku or even to deploy in binary form.

Once you have a compiled Ratpack application in the Heroku environment (either through building with another build tool or by binary deployment), you can simply start the application by using java directly.

web: java ratpack.groovy.GroovyRatpackMain

See the launching chapter for more detail on starting Ratpack applications.

24.3 General Considerations

24.3.1 Port

Heroku assigns each application an ephemeral port number, made available by the PORT environment variable. Ratpack honors this environment variable by default if the ratpack.port system property is not set.