Getting Started on Heroku with Java

Introduction

This tutorial will have you deploying a Java app in minutes.

Hang on for a few more minutes to learn how it all works, so you can make the most out of Heroku.

The tutorial assumes that you already have:

• A free Heroku account
• Java 8 installed
• Maven 3 installed

If you’d prefer to use Gradle instead of Maven, please see the Getting Started with Gradle on Heroku guide.

Set up

In this step you’ll install the Heroku Command Line Interface (CLI). You use the CLI to manage and scale your applications, provision add-ons, view your application logs, and run your application locally.

Download and run the installer for your platform:

Once installed, you can use the heroku command from your command shell.

Log in using the email address and password you used when creating your Heroku account:

$ heroku login
Enter your Heroku credentials.
Email: java@example.com
Password:

Authenticating is required to allow both the heroku and git commands to operate.

Note that if you’re behind a firewall that requires use of a proxy to connect with external HTTP/HTTPS services, you can set the HTTP_PROXY or HTTPS_PROXY environment variables in your local development environment before running the heroku command.

Prepare the app

In this step, you will prepare a sample application that’s ready to be deployed to Heroku.

To create a local copy of a sample app that you can deploy to Heroku, execute the following commands in your local command shell or terminal:

$ git clone https://github.com/heroku/java-getting-started.git
$ cd java-getting-started

You now have a functioning Git repository that contains a simple Java application. The application includes a pom.xml file, which is used by Java’s dependency manager, Maven.

Deploy the app

In this step you’ll deploy the sample app to Heroku.

First, create an app on Heroku, which prepares Heroku to receive your source code:

$ heroku create
Creating warm-eyrie-9006... done, stack is cedar-14
http://warm-eyrie-9006.herokuapp.com/ | https://git.heroku.com/warm-eyrie-9006.git
Git remote heroku added

When you create an app, a Git remote (named heroku) is also created and associated with your local Git repository.

By default, Heroku generates a random name (in this case warm-eyrie-9006) for your app. You can pass a parameter to specify your own app name.

Now deploy your code:

$ git push heroku master
Initializing repository, done.
Counting objects: 68, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (19/19), done.
Writing objects: 100% (68/68), 7.07 KiB | 0 bytes/s, done.
Total 68 (delta 22), reused 65 (delta 22)

remote: -----> Java app detected
remote: -----> Installing OpenJDK 1.8... done
remote: -----> Executing: ./mvnw -DskipTests clean dependency:list install
...
remote:        [INFO] ------------------------------------------------------------------------
remote:        [INFO] BUILD SUCCESS
remote:        [INFO] ------------------------------------------------------------------------
remote:        [INFO] Total time: 14.062 s
remote:        [INFO] Finished at: 2017-04-20T15:06:01+00:00
remote:        [INFO] Final Memory: 38M/270M
remote:        [INFO] ------------------------------------------------------------------------
...
-----> Discovering process types
       Procfile declares types -> web

-----> Compressing... done, 62.7MB
-----> Launching... done, v7
       http://warm-eyrie-9006.herokuapp.com/ deployed to Heroku

To git@heroku.com:warm-eyrie-9006.git
 * [new branch]      master -> master

The application is now deployed. Ensure that at least one instance of the app is running:

$ heroku ps:scale web=1

Now visit the app at the URL generated by its app name. As a handy shortcut, you can open the website like so:

$ heroku open

View logs

Heroku aggregates all of the output streams from both your app and the platform’s components into a single channel of time-ordered logs.

View information about your running app using the heroku logs --tail command:

$ heroku logs --tail
2017-04-20T15:06:14.198559+00:00 heroku[web.1]: Starting process with command `java $JAVA_OPTS -Dserver.port=43161 -jar target/java-getting-started-1.0.jar`
2017-04-20T15:06:16.478043+00:00 app[web.1]: Setting JAVA_TOOL_OPTIONS defaults based on dyno size. Custom settings will override them.
2017-04-20T15:06:16.484066+00:00 app[web.1]: Picked up JAVA_TOOL_OPTIONS: -Xmx350m -Xss512k -Dfile.encoding=UTF-8
2017-04-20T15:06:19.396477+00:00 app[web.1]:   _    _                _
2017-04-20T15:06:19.396487+00:00 app[web.1]:  | |  | |              | |
2017-04-20T15:06:19.396488+00:00 app[web.1]:  | |__| | ___ _ __ ___ | | ___   _
2017-04-20T15:06:19.396489+00:00 app[web.1]:  |  __  |/ _ \ '__/ _ \| |/ / | | |
2017-04-20T15:06:19.396489+00:00 app[web.1]:  | |  | |  __/ | | (_) |   <| |_| |
2017-04-20T15:06:19.396490+00:00 app[web.1]:  |_|  |_|\___|_|  \___/|_|\_\\__,_|
2017-04-20T15:06:19.396491+00:00 app[web.1]:
2017-04-20T15:06:19.396491+00:00 app[web.1]: :: Built with Spring Boot :: 2.0.0.RELEASE
...
2017-04-20T15:06:33.472964+00:00 app[web.1]: 2017-04-20 15:06:33.472  INFO 4 --- [           main] com.example.Main               : Started Main in 15.345 seconds (JVM running for 16.989)
2017-04-20T15:06:33.778990+00:00 heroku[web.1]: State changed from starting to up

Visit your application in the browser again to generate another log message.

Press CTRL+C to stop streaming logs.

Define a Procfile

Heroku apps use a special plaintext file called the Procfile to explicitly declare what command should be executed to start your app.

The Procfile in the example app you deployed looks like this:

web: java -jar target/java-getting-started-1.0.jar

This declares a single process type, web, and the command needed to run it. The name web is important here. It declares that this process type will be attached to Heroku’s HTTP routing stack, and it will be able to receive web traffic.

Procfiles can contain additional process types. For example, you might declare one for a background worker that processes items off of a queue.

Scale the app

Right now, your app is running on a single web dyno. A dyno is a lightweight Linux container that runs the command specified in your Procfile.

You can check how many dynos are running using the heroku ps command:

$ heroku ps
=== web (Free): web: java -jar target/java-getting-started-1.0.jar (1)
web.1: up 2016/07/07 09:06:41 +0100 (~ 4m ago)

By default, your app is deployed on a free dyno. Free dynos sleep after thirty minutes of inactivity (i.e., if they don’t receive any traffic). This causes a delay of a few seconds for the first request upon waking. Subsequent requests will perform normally.

Free dynos consume from a monthly, account-level quota of free dyno hours. As long as the quota is not exhausted, your free apps can continue to run.

To avoid dyno sleeping, you can upgrade to a hobby or professional dyno type as described in Dyno Types. For example, if you migrate your app to a professional dyno, you can easily scale it by running a command telling Heroku to spin up a specific number of dynos, each running your web process type.

Scaling an application on Heroku is equivalent to changing the number of dynos that are running.

Scale the number of web dynos to zero:

$ heroku ps:scale web=0

Access the app again by refreshing your browser or running heroku open. You will get an error message because your app no longer has any web dynos available to serve requests.

Scale it up again:

$ heroku ps:scale web=1

To prevent abuse, scaling a non-free application to more than one dyno requires account verification.

Declare app dependencies

Heroku automatically identifies an app as a Java app if it contains a pom.xml file in the root directory. You can create a pom.xml file for your own apps with the mvn archetype:create command.

The demo app you deployed already has a pom.xml (see it here). Here’s an excerpt:

  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    ...
  </dependencies>

The pom.xml file specifies dependencies that should be installed with your application. When an app is deployed, Heroku reads this file and installs the dependencies by running mvn clean install.

Another file, system.properties, indicates the version of Java to use (Heroku supports many different versions). The contents of this optional file are straightforward:

java.runtime.version=1.8

Run mvn clean install in your local directory to install the dependencies, preparing your system for running the app locally. Note that this app requires Java 8, but you can push your own apps using a different version of Java.

$ mvn clean install
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building spring-getting-started 1.0
[INFO] ------------------------------------------------------------------------
[INFO]
...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 5.069s
[INFO] Finished at: Thu Apr 20 10:11:16 CDT 2017
[INFO] Final Memory: 29M/298M
[INFO] ------------------------------------------------------------------------

If you do not have Maven installed, or get an error like 'mvn' is not recognized as an internal or external command, then you can use the wrapper command instead by running mvnw clean install on Windows or ./mvnw clean install on Mac and Linux. This both installs Maven and runs the Maven command.

The Maven process compiles and build a JAR, with dependencies, placing it into your application’s target directory. This process is accomplished with the spring-boot-maven-plugin in the pom.xml.

If you aren’t using Spring in your app, you can accomplish this with the following plugin configuration in the pom.xml file.

<plugin>
  <artifactId>maven-assembly-plugin</artifactId>
  <version>3.0.0</version>
  <configuration>
  <descriptorRefs>
    <descriptorRef>jar-with-dependencies</descriptorRef>
  </descriptorRefs>
  <finalName>helloworld</finalName>
</plugin>

Once dependencies are installed, you can run your app locally.

Run the app locally

Start your application locally with the heroku local CLI command (make sure you’ve already run mvn clean install):

$ heroku local web
[OKAY] Loaded ENV .env File as KEY=VALUE Format
10:15:41 AM web.1 |    _    _                _
10:15:41 AM web.1 |   | |  | |              | |
10:15:41 AM web.1 |   | |__| | ___ _ __ ___ | | ___   _
10:15:41 AM web.1 |   |  __  |/ _ \ '__/ _ \| |/ / | | |
10:15:41 AM web.1 |   | |  | |  __/ | | (_) |   <| |_| |
10:15:41 AM web.1 |   |_|  |_|\___|_|  \___/|_|\_\\__,_|
10:15:41 AM web.1 |  :: Built with Spring Boot :: 2.0.0.RELEASE
...
10:15:58 AM web.1 |  2017-04-20 10:15:46.933  INFO 71653 --- [           main] s.b.c.e.t.TomcatEmbeddedServletContainer : Tomcat started on port(s): 5000 (http)
10:15:58 AM web.1 |  2017-04-20 10:15:46.940  INFO 71653 --- [           main] com.example.Main               : Started Main in 6.057 seconds (JVM running for 7.178)

Just like the Heroku platform, heroku local examines your Procfile to determine what command to run.

Open http://localhost:5000 with your web browser. You should see your app running locally.

To stop the app from running locally, go back to your terminal window and press CTRL+C to exit.

Push local changes

In this step you’ll learn how to make local changes to your app and deploy them to Heroku. As an example, you’ll add a dependency and some code that uses it.

Modify pom.xml to include a dependency for jscience. The <dependencies> section should look something like this:

  <dependencies>
    ...
    <dependency>
      <groupId>org.postgresql</groupId>
      <artifactId>postgresql</artifactId>
      <version>9.4.1212</version>
    </dependency>
    <dependency>
      <groupId>com.zaxxer</groupId>
      <artifactId>HikariCP</artifactId>
      <version>2.6.0</version>
    </dependency>
    <dependency>
      <groupId>org.jscience</groupId>
      <artifactId>jscience</artifactId>
      <version>4.3.1</version>
    </dependency>
  </dependencies>

Now add the following import statements to src/main/java/com/example/Main.java to import the library:

import static javax.measure.unit.SI.KILOGRAM;
import javax.measure.quantity.Mass;
import org.jscience.physics.model.RelativisticModel;
import org.jscience.physics.amount.Amount;

Add the following hello method to Main.java:

@RequestMapping("/hello")
String hello(Map<String, Object> model) {
    RelativisticModel.select();
    Amount<Mass> m = Amount.valueOf("12 GeV").to(KILOGRAM);
    model.put("science", "E=mc^2: 12 GeV = " + m.toString());
    return "hello";
}

Finally, create a src/main/resources/templates/hello.html file with these contents:

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{fragments/layout :: layout (~{::body},'hello')}">
<body>
  <div class="container">
    <p th:text="${science}"/>
  </div>
</body>
</html>

Here’s the final source code for Main.java - yours should look similar. Here’s a diff of all the local changes you should have made.

Now test your changes locally:

$ mvn clean install
$ heroku local web

Visiting your application’s /hello path at http://localhost:5000/hello, you should see some great scientific conversions displayed:

E=mc^2: 12 GeV = (2.139194076302506E-26 ± 1.4E-42) kg

Now you can deploy. Almost every Heroku deployment follows this same pattern. First, use the git add command to stage your modified files for commit:

$ git add .

Next, commit the changes to the repository:

$ git commit -m "Demo"

Now deploy, just as you did previously:

$ git push heroku master

Finally, check that your updated code is successfully deployed:

$ heroku open hello

Define config vars

Heroku lets you externalize your app’s configuration by storing data such as encryption keys or external resource addresses in config vars.

At runtime, config vars are exposed to your app as environment variables. For example, modify src/main/java/com/example/Main.java so that the method obtains an energy value from the ENERGY environment variable:

@RequestMapping("/hello")
String hello(Map<String, Object> model) {
    RelativisticModel.select();
    String energy = System.getenv().get("ENERGY");
    if (energy == null) {
       energy = "12 GeV";
    }
    Amount<Mass> m = Amount.valueOf(energy).to(KILOGRAM);
    model.put("science", "E=mc^2: " + energy + " = "  + m.toString());
    return "hello";
}

Now compile the app again so that this change is integrated by running mvn clean install.

heroku local automatically sets up your local environment based on the contents of the .env file in your app’s root directory. Your sample app already includes a .env file with the following contents:

ENERGY=20 GeV

If you run the app with heroku local and visit it at http://localhost:5000/hello, you’ll see the conversion value for 20 GeV.

To set the config var on Heroku, execute the following:

$ heroku config:set ENERGY="20 GeV"
Setting config vars and restarting warm-eyrie-9006... done, v10
ENERGY: 20 GeV

View the config vars that are set using heroku config:

$ heroku config
== warm-eyrie-9006 Config Vars
PAPERTRAIL_API_TOKEN: erdKhPeeeehIcdfY7ne
ENERGY: 20 GeV
...

Deploy your updated application to Heroku to see this in action.

Start a one-off dyno

The heroku run command lets you run maintenance and administrative tasks on your app in a one-off dyno. It can also lets you launch a REPL process attached to your local terminal for experimenting in your app’s environment, or code that you deployed with your application:

$ heroku run bash
Running `bash` attached to terminal... up, run.9640
~ $ java -version
openjdk version "1.8.0_121-cedar14"
OpenJDK Runtime Environment (build 1.8.0_121-cedar14-b13)
OpenJDK 64-Bit Server VM (build 25.121-b13, mixed mode)

If you receive an error, Error connecting to process, then you might need to configure your firewall.

Don’t forget to type exit to exit the shell and terminate the dyno.

Provision add-ons

Add-ons are cloud services that provide additional services for your application, such as databases, logging, and monitoring.

By default, Heroku stores your app’s 1500 most recent log lines. However, the full log stream is available as a service, and several logging add-ons are available that provide features such as log persistence, search, and alerting.

In this step you’ll provision one of these logging add-ons, Papertrail.

Provision the Papertrail add-on like so:

$ heroku addons:create papertrail
Adding papertrail on warm-eyrie-9006... done, v8 (free)
Welcome to Papertrail. Questions and ideas are welcome (support@papertrailapp.com). Happy logging!
Use `heroku addons:docs papertrail` to view documentation.

The add-on is now deployed and configured for your application. You can list your app’s active add-ons like so:

$ heroku addons

To see this particular add-on in action, visit your application’s Heroku URL a few times. Each visit generates more log messages, which should now be routed to the Papertrail add-on. Visit the Papertrail console to see the log messages:

$ heroku addons:open papertrail

Your browser will open up a Papertrail web console that shows the latest log events. The interface lets you search and set up alerts:

Use a database

Heroku provides managed data services for Postgres and Redis, and the add-on marketplace provides a variety of additional data services, including MongoDB and MySQL.

In this step you’ll learn about the free Heroku Postgres add-on that is provisioned automatically with all Java app deploys.

Heroku Postgres is itself an add-on, so you can use the heroku addons command for an overview of the database provisioned for your app:

$ heroku addons

Add-on                                      Plan       Price  State
──────────────────────────────────────────  ─────────  ─────  ───────
heroku-postgresql (holding-carefully-4665)  hobby-dev  free   created
 ├─ as DATABASE
 └─ as HEROKU_POSTGRESQL_PINK

papertrail (papertrail-rugged-42538)        choklad    free   created
 └─ as PAPERTRAIL

Listing your app’s config vars will display the URL that your app is using to connect to the database (DATABASE_URL):

$ heroku config
=== warm-eyrie-9006 Config Vars
DATABASE_URL:               postgres://qplhasewkqyxp:YXDPSRus9MrU4HglCPzjhOevee@ec2-54-204-47-58.compute-1.amazonaws.com:5432/dc9qsdnghia6v1
...

The heroku pg command provides more in-depth information on your app’s Heroku Postgres databases:

$ heroku pg
== HEROKU_POSTGRESQL_BLUE_URL (DATABASE_URL)
Plan:        Hobby-dev
Status:      Available
Connections: 0
PG Version:  9.3.3
Created:     2014-08-08 13:54 UTC
Data Size:   6.5 MB
Tables:      0
Rows:        0/10000 (In compliance)
Fork/Follow: Unsupported
Rollback:    Unsupported

This indicates that the app has a Hobby-dev database (the free plan), running Postgres 9.3.3, currently with zero rows of data.

The example app you deployed already has database functionality, which you can reach by visiting your app’s /db path. For example, if your app’s root URL is https://wonderful-app-287.herokuapp.com/ then visit https://wonderful-app-287.herokuapp.com/db.

The code to access the database is straightforward. Here’s the method to insert values into a table called tick:

@Value("${spring.datasource.url}")
private String dbUrl;

@Autowired
private DataSource dataSource;

...

@RequestMapping("/db")
String db(Map<String, Object> model) {
    try (Connection connection = dataSource.getConnection()) {
      Statement stmt = connection.createStatement();
      stmt.executeUpdate("CREATE TABLE IF NOT EXISTS ticks (tick timestamp)");
      stmt.executeUpdate("INSERT INTO ticks VALUES (now())");
      ResultSet rs = stmt.executeQuery("SELECT tick FROM ticks");

      ArrayList<String> output = new ArrayList<String>();
      while (rs.next()) {
        output.add("Read from DB: " + rs.getTimestamp("tick"));
      }

      model.put("records", output);
      return "db";
    } catch (Exception e) {
      model.put("message", e.getMessage());
      return "error";
    }
}

@Bean
public DataSource dataSource() throws SQLException {
    if (dbUrl == null || dbUrl.isEmpty()) {
      return new HikariDataSource();
    } else {
      HikariConfig config = new HikariConfig();
      config.setJdbcUrl(dbUrl);
      return new HikariDataSource(config);
    }
}

This ensures that when you access your app using the /db route, a new row is added to the tick table, and all rows are then returned so that they can be rendered in the output.

The HikariCP database connection pool is initialized with the configuration value spring.datasource.url, which is defined in src/main/resources/application.properties like this:

spring.datasource.url: ${JDBC_DATABASE_URL:}

This sets spring.datasource.url to the value in the JDBC_DATABASE_URL environment variable, set by the database add-on, and establishes a pool of connections to the database.

Deploy your changes to Heroku. Now, when you access your app’s /db route, you will see something like this:

Database Output
* Read from DB: 2014-08-08 14:48:25.155241
* Read from DB: 2014-08-08 14:51:32.287816
* Read from DB: 2014-08-08 14:51:52.667683

Assuming that you have Postgres installed locally, use the heroku pg:psql command to connect to the remote database and see all the rows:

$ heroku pg:psql
heroku pg:psql
psql (9.3.2, server 9.3.3)
SSL connection (cipher: DHE-RSA-AES256-SHA, bits: 256)
Type "help" for help.
=> SELECT * FROM ticks;
            tick
----------------------------
 2014-08-08 14:48:25.155241
 2014-08-08 14:51:32.287816
 2014-08-08 14:51:52.667683
 2014-08-08 14:51:53.1871
 2014-08-08 14:51:54.75061
 2014-08-08 14:51:55.161848
 2014-08-08 14:51:56.197663
 2014-08-08 14:51:56.851729
(8 rows)
=> \q

Read more about Heroku PostgreSQL.

A similar technique can be used to install MongoDB or Redis add-ons.

Next steps

Congratulations! You now know how to deploy an app, change its configuration, scale it, view logs, and attach add-ons.

Here’s some recommended reading to continue your Heroku journey:

• How Heroku Works provides a technical overview of the concepts you’ll encounter while writing, configuring, deploying, and running apps.
• The Java category provides more in-depth information on developing and deploying Java apps.
• The Deployment category provides a variety of powerful integrations and features to help streamline and simplify your deployments.