Getting Started on Heroku with Java

Introduction

Deploy a Java app in minutes with this tutorial.

The tutorial assumes that you already have:

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

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

Set Up

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

Download and run the installer for your platform:

After installation completes, you can use the heroku command from your terminal.

Use the heroku login command to log in to the Heroku CLI:

$ heroku login
heroku: Press any key to open up the browser to login or q to exit
 ›   Warning: If browser does not open, visit
 ›   https://cli-auth.heroku.com/auth/browser/***
heroku: Waiting for login...
Logging in... done
Logged in as me@example.com

This command opens your web browser to the Heroku login page to complete authentication. If your browser is already logged in to Heroku, click the Log in button displayed on the page.

Both the heroku and git commands require this authentication to work correctly.

If you’re behind a firewall that requires a proxy to connect with external HTTP/HTTPS services, 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 clone a sample application and prepare to deploy it to Heroku.

Create a local copy of the sample app by executing the following commands in your local command shell or terminal:

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

This functioning Git repository contains a simple Java application. The application includes a Procfile, a special plaintext file used by Heroku apps. You explicitly declare the processes and commands used to start your app in this file.

The Procfile in the example app source code looks like this:

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

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

Procfiles can contain additional process types. For example, you can declare a background worker that processes items off a queue. This tutorial doesn’t cover other processes but you can refer to The Procfile and The Process Model for more info.

The example app also includes a pom.xml file, which is used by Java’s dependency manager, Maven. The next step covers how to use this file to declare dependencies.

Declare App Dependencies

Heroku automatically identifies an app as a Java app if it contains a pom.xml file in the root directory. When a Java app is detected, Heroku adds the official Java buildpack to your app, which installs the dependencies for your application. You can create a pom.xml file for your own apps with the mvn archetype:generate command.

The example 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>

When deploying an app, Heroku reads this file and installs the dependencies by running mvn clean install. Take a look at the dependencies listed in your pom.xml.

Another file, system.properties, indicates the version of Java to use. The contents of this optional file look like:

java.runtime.version=1.8

Heroku supports many different versions. You can push your own apps using a different version of Java.

Deploy the App

Create an app on Heroku to prepare it to receive your source code for deployment:

$ heroku create
Creating app... done, calm-beyond-57162
https://calm-beyond-57162.herokuapp.com/ | https://git.heroku.com/calm-beyond-57162.git

This command both creates an app and a Git remote (named heroku) associated with your local Git repository.

By default, Heroku generates a random name for your app. You can pass a parameter to specify your own app name.

Now deploy your code:

$ git push heroku main
remote: Compressing source files... done.
remote: Building source:
remote:
remote: -----> Building on the Heroku-20 stack
remote: -----> Determining which buildpack to use for this app
remote: -----> Java app detected
remote: -----> Installing JDK 1.8... done
remote: -----> Executing Maven
...
remote:        [INFO] ------------------------------------------------------------------------
remote:        [INFO] BUILD SUCCESS
remote:        [INFO] ------------------------------------------------------------------------
remote:        [INFO] Total time:  16.451 s
remote:        [INFO] Finished at: 2021-09-28T02:37:53Z
remote:        [INFO] ------------------------------------------------------------------------
remote: -----> Discovering process types
remote:        Procfile declares types -> web
remote:
remote: -----> Compressing...
remote:        Done: 72.4M
remote: -----> Launching...
remote:        Released v5
remote:        https://calm-beyond-57162.herokuapp.com/ deployed to Heroku
remote:
remote: Verifying deploy... done.
To https://git.heroku.com/calm-beyond-57162.git
 * [new branch]      main -> main

By default, your app deploys on a free dyno. A dyno is a lightweight Linux container that runs the command specified in your Procfile. After deployment, ensure that you have one web dyno running the app. You can check how many dynos are running using the heroku ps command:

$ heroku ps
Free dyno hours quota remaining this month: 997h 48m (99%)
Free dyno usage for this app: 0h 0m (0%)
For more information on dyno sleeping and how to upgrade, see:
https://devcenter.heroku.com/articles/dyno-sleeping

=== web (Free): java -jar target/java-getting-started-1.0.jar (1)
web.1: up 2021/09/27 22:38:10 -0400 (~ 6s ago)

The running web dynos serve requests. Visit the app at the URL generated by its app name. As a handy shortcut, you can open the website with:

$ heroku open

Free dynos sleep after thirty minutes of inactivity (for example, if they don’t receive any traffic). This behavior causes a delay of a few seconds for the first request upon waking. Subsequent requests perform normally. Free dynos consume from a monthly, account-level quota of free dyno hours. As long as you haven’t exhausted the quota, your free apps can continue to run.

To avoid dyno sleeping, upgrade to a hobby or professional dyno type as described in Dyno Types.

Scale the App

Horizontal scaling an application on Heroku is equivalent to changing the number of running dynos.

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 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.

View Logs

Heroku aggregates all 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
2021-09-28T02:38:10.241301+00:00 app[web.1]: 2021-09-28 02:38:10.241  INFO 4 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 29967 (http) with context path ''
2021-09-28T02:38:10.259364+00:00 app[web.1]: 2021-09-28 02:38:10.259  INFO 4 --- [           main] com.example.Main                         : Started Main in 4.128 seconds (JVM running for 4.754)
2021-09-28T02:38:10.473747+00:00 heroku[web.1]: State changed from starting to up
2021-09-28T02:38:20.063423+00:00 app[api]: Scaled to web@0:Free by user developer@example.com2021-09-28T02:38:22.169497+00:00 app[api]: Scaled to web@1:Free by user developer@example.com2021-09-28T02:38:23.674418+00:00 heroku[router]: at=error code=H10 desc="App crashed" method=GET path="/" host=calm-beyond-57162.herokuapp.com request_id=b556d972-c53d-423d-bdc6-76064b678ec1 fwd="204.14.236.156" dyno= connect= service= status=503 bytes= protocol=https
2021-09-28T02:38:24.206795+00:00 app[web.1]: 2021-09-28 02:38:24.206  INFO 4 --- [io-29967-exec-3] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring DispatcherServlet 'dispatcherServlet'
2021-09-28T02:38:24.206859+00:00 app[web.1]: 2021-09-28 02:38:24.206  INFO 4 --- [io-29967-exec-3] o.s.web.servlet.DispatcherServlet        : Initializing Servlet 'dispatcherServlet'
2021-09-28T02:38:24.212934+00:00 app[web.1]: 2021-09-28 02:38:24.212  INFO 4 --- [io-29967-exec-3] o.s.web.servlet.DispatcherServlet        : Completed initialization in 6 ms
2021-09-28T02:38:24.359785+00:00 heroku[router]: at=info method=GET path="/favicon.ico" host=calm-beyond-57162.herokuapp.com request_id=5ff143f2-5d22-4a62-8141-23946b1c8adc fwd="204.14.236.156" dyno=web.1 connect=0ms service=183ms status=404 bytes=346 protocol=https

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

Press CTRL+C to stop streaming logs.

By default, Heroku stores your app’s 1500 most recent log lines. You can provision a logging add-on or implement your own log drain for long-term storage. In the next step, you add a logging add-on to your app.

Provision Add-ons

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

Several logging add-ons are available that provide features such as log persistence, search, and alerting. Papertrail is one such add-on with a free plan.

Provision the add-on like so:

$ heroku addons:create papertrail
Creating papertrail on calm-beyond-57162... free
Welcome to Papertrail. Questions and ideas are welcome (technicalsupport@solarwinds.com). Happy logging!
Created papertrail-asymmetrical-88691 as PAPERTRAIL_API_TOKEN
Use heroku addons:docs papertrail to view documentation

This command provisions the add-on and configures it for your application. To see this particular add-on in action, visit your application’s Heroku URL a few times. Each visit generates more log messages, which routes to the Papertrail add-on. Visit the Papertrail console to see the log messages:

$ heroku addons:open papertrail

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

You can list all of your app’s active add-ons like so:

$ heroku addons

Running this command for your sample app lists its Papertrail and Heroku Postgres add-ons. Heroku automatically provisions a Postgres database add-on with all Java app deploys. You learn how to use this database in the next step.

Use a Database

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

Heroku provisions a Heroku Postgres add-on on the free hobby-dev plan automatically with all Java app deploys.

Use the heroku addons command for an overview of the database provisioned for your app:

$ heroku addons

Add-on                                        Plan       Price  State
────────────────────────────────────────────  ─────────  ─────  ───────
heroku-postgresql (postgresql-concave-20762)  hobby-dev  free   created
 └─ as DATABASE

papertrail (papertrail-asymmetrical-88691)    choklad    free   created
 └─ as PAPERTRAIL

The table above shows add-ons and the attachments to the current app (calm-beyond-57162) or other apps.

Listing your app’s config vars displays the URL that your app uses to connect to the database (DATABASE_URL):

$ heroku config
=== calm-beyond-57162 Config Vars
DATABASE_URL:         postgres://avhrhofbiyvpct:3ab23026d0fc225bde4544cedabc356904980e6a02a2418ca44d7fd19dad8e03@ec2-23-21-4-7.compute-1.amazonaws.com:5432/d8e8ojni26668k
PAPERTRAIL_API_TOKEN: ChtIUu9fHbij1cBn7y6z

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

$ heroku pg
=== DATABASE_URL
Plan:                  Hobby-dev
Status:                Available
Connections:           10/20
PG Version:            13.4
Created:               2021-09-28 02:38 UTC
Data Size:             7.9 MB/1.00 GB (In compliance)
Tables:                0
Rows:                  0/10000 (In compliance)
Fork/Follow:           Unsupported
Rollback:              Unsupported
Continuous Protection: Off
Add-on:                postgresql-concave-20762

Running this command for your app indicates that the app has a Hobby-dev Postgres database (the free plan), 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://example-app-287.herokuapp.com/ then visit https://example-app-287.herokuapp.com/db.

You 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
psql (10.1, server 9.6.10)
SSL connection (protocol: TLSv1.2, cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, compression: off)
Type "help" for help.

DATABASE=> SELECT * FROM ticks;
            tick
----------------------------
2018-03-01 20:53:27.148139
2018-03-01 20:53:29.288995
2018-03-01 20:53:29.957118
2018-03-01 21:07:28.880162
(4 rows)
=> \q

The code in the example app looks like this:

  private DataSource dataSource;

  public static void main(String[] args) throws Exception {
    SpringApplication.run(Main.class, args);
  }

  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 method adds a new row to the tick table when you access your app using the /db route. It then returns all rows to render in the output.

The spring.datasource.url shown in example app code refers to the configuration value defined in src/main/resources/application.properties. The HikariCP database connection pool initializes with this value.

The example app has spring.datasource.url set to the value in the JDBC_DATABASE_URL to establish a pool of connections to the database:

spring.datasource.url: ${JDBC_DATABASE_URL:}

The official Heroku Java buildpack that’s automatically added to your app sets this JDBC_DATABASE_URL environment variable. This variable is dynamic and doesn’t appear in your list of configuration variables when running heroku config. You can view it by running the following command:

$ heroku run echo \$JDBC_DATABASE_URL

Read more about Heroku PostgreSQL. You can also install MongoDB, Redis, or other data add-ons via heroku addons:create.

Prepare the Local Environment

In the following steps, you learn how to work with your app locally and push changes to Heroku. Begin by installing your dependencies locally in this step.

Ensure that you have Maven installed before running mvn clean install in your local directory. This command installs the dependencies, preparing your system to run the app locally.

$ mvn clean install
...
[INFO] Installing /Users/example-user/java-getting-started/pom.xml to /Users/example-user/.m2/repository/com/example/java-getting-started/1.0/java-getting-started-1.0.pom
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  2.201 s
[INFO] Finished at: 2021-09-27T22:38:43-04:00
[INFO] ------------------------------------------------------------------------

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

If you aren’t using Spring in your app, add 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>
  </configuration>
</plugin>

After installing dependencies, you can run your app locally. However, the /db route doesn’t work as you must connect to a database. If you want to access the /db route when running locally, create a local Postgres database and update your local .env file. heroku local, the command used to run apps locally, automatically sets up your environment based on the .env file in your app’s root directory. Set the JDBC_DATABASE_URL environment variable with your local Postgres database’s connection string:

JDBC_DATABASE_URL=jdbc:postgresql://localhost:5432/java_database_name

Your local environment is now ready to run your app and connect to the database.

Run the App Locally

Ensure you’ve already run mvn clean install before running your app locally.

Start your application locally with the heroku local CLI command:

$ heroku local web
...
10:38:47 PM web.1 |  2021-09-27 22:38:47.549  INFO 75467 --- [           main] o.s.s.concurrent.ThreadPoolTaskExecutor  : Initializing ExecutorService 'applicationTaskExecutor'
10:38:47 PM web.1 |  2021-09-27 22:38:47.657  INFO 75467 --- [           main] o.s.b.a.w.s.WelcomePageHandlerMapping    : Adding welcome page template: index
10:38:48 PM web.1 |  2021-09-27 22:38:48.008  INFO 75467 --- [           main] o.s.b.a.e.web.EndpointLinksResolver      : Exposing 2 endpoint(s) beneath base path '/actuator'
10:38:48 PM web.1 |  2021-09-27 22:38:48.061  INFO 75467 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 5000 (http) with context path ''

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

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

If you want to access the app’s /db route locally, ensure that your local Postgres database is running before you visit the URL.

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 make local changes to your app and deploy them to Heroku. Add the following dependency and some code that uses it.

Modify pom.xml to include a dependency for jscience by adding the following code inside the <dependencies> element:

In file pom.xml, on line 28 add:

<dependency>
  <groupId>org.jscience</groupId>
  <artifactId>jscience</artifactId>
  <version>4.3.1</version>
</dependency>

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

In file src/main/java/com/example/Main.java, on line 19 add:

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 to use the library:

In file src/main/java/com/example/Main.java, on line 59 add:

@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:

In file src/main/resources/templates/hello.html write:

<!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. Ensure that your changes look similar. Here’s a diff of all the local changes made.

Test your changes locally:

$ mvn clean install
...
[INFO] Installing /Users/example-user/java-getting-started/pom.xml to /Users/example-user/.m2/repository/com/example/java-getting-started/1.0/java-getting-started-1.0.pom
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  2.268 s
[INFO] Finished at: 2021-09-27T22:38:51-04:00
[INFO] ------------------------------------------------------------------------
$ heroku local web
...
10:38:55 PM web.1 |  2021-09-27 22:38:55.496  INFO 75574 --- [           main] o.s.s.concurrent.ThreadPoolTaskExecutor  : Initializing ExecutorService 'applicationTaskExecutor'
10:38:55 PM web.1 |  2021-09-27 22:38:55.608  INFO 75574 --- [           main] o.s.b.a.w.s.WelcomePageHandlerMapping    : Adding welcome page template: index
10:38:55 PM web.1 |  2021-09-27 22:38:55.951  INFO 75574 --- [           main] o.s.b.a.e.web.EndpointLinksResolver      : Exposing 2 endpoint(s) beneath base path '/actuator'
10:38:56 PM web.1 |  2021-09-27 22:38:56.004  INFO 75574 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 5000 (http) with context path ''

Visiting your application’s /hello path at http://localhost:5000/hello, which displays some scientific conversions:

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

After testing, deploy your changes. 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 main

Finally, check that your updated code successfully deployed by opening your browser to that route:

$ 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:

In file src/main/java/com/example/Main.java, on line 56 add:

@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";
}

Recompile the app to integrate this change by running mvn clean install.

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

ENERGY=20 GeV

Your local .env file also includes the JDBC_DATABASE_URL variable if you set it during the Run the App Locally step.

Run the app with heroku local and visit http://localhost:5000/hello to see the conversion value for 20 GeV.

Now that you know it works as expected locally, set this variable as a config var on your app running on Heroku. Execute the following:

$ heroku config:set ENERGY="20 GeV"
Setting ENERGY and restarting calm-beyond-57162... done, v9
ENERGY: 20 GeV

View the app’s config vars using heroku config to verify you’ve done it correctly:

$ heroku config
=== calm-beyond-57162 Config Vars
DATABASE_URL:         postgres://avhrhofbiyvpct:3ab23026d0fc225bde4544cedabc356904980e6a02a2418ca44d7fd19dad8e03@ec2-23-21-4-7.compute-1.amazonaws.com:5432/d8e8ojni26668k
ENERGY:               20 GeV
PAPERTRAIL_API_TOKEN: ChtIUu9fHbij1cBn7y6z

Deploy your local changes to Heroku and visit the /hello route to see your changes in action:

$ git add .
$ git commit -m "Demo"
$ git push heroku main
$ heroku open hello

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 also lets you launch a REPL process attached to your local terminal for experimenting in your app’s environment or your deployed application code:

$ heroku run java -version
Running java -version on calm-beyond-57162... connecting, run.4685 (Free)Running java -version on calm-beyond-57162... up, run.4685 (Free)
openjdk version "1.8.0_302-heroku"
OpenJDK Runtime Environment (build 1.8.0_302-heroku-b08)
OpenJDK 64-Bit Server VM (build 25.302-b08, mixed mode)

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

Remember to type exit to exit the shell and terminate the dyno.

Next Steps

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

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

• How Heroku Works provides a technical overview of the concepts encountered 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.
• Learn more about the Heroku developer experience and CI/CD features in the Heroku Enterprise Developer Learning Journey.