Tutorial & Screencast: Java on Heroku with Eclipse

2012-01-24

UPDATE: There is a new and better way to get started with Java on Heroku using Eclipse. For details check out:
Screencast: Java Template Apps on Heroku

The rest of this post is now legacy stuff.

I recorded a screencast and put together some instructions on how to try out Java on Heroku using just a web browser and Eclipse. First, check out the screencast:

Here are steps you can follow to get started running Java on Heroku with Eclipse and your browser:

Prerequisites) Install the EGit and Maven (m2e) Eclipse plugins into your Eclipse. In Eclipse select the “Help” menu, select “Install new Software”, from the “Work With” drop-down menu select “All Available Sites”, and enter “EGit” in the filter box. After the plugin list has loaded (could take a minute) then select the “Eclipse EGit” plugin, select “Next”, and finish walking through the wizard to the plugin. Then do the same for the Maven Plugin “m2e”.

Step 1) Go to java.herokuapp.com and select an application template. In the screencast I used the “Simple Java Web App with Maven and Tomcat” option since it uses the familiar WAR packaging and Tomcat. Enter your email address and click the “Go!” button. This will create a copy of the template, upload it to Heroku, and assign you as the owner of the app. When the app is created you will see some instructions and a link to the application running on Heroku.

Step 2) You should have received an email from Heroku indicating that an application has been shared with you. If this is your first time using Heroku you will need to click the account setup link in the email in order to set your password on Heroku.

Step 3) If this is the first time you have used Heroku then you will need to create and associate a SSH key with your Heroku account. This will be used to authenticate you for git file transfers (to copy the application to/from Heroku). The standard way to do this is with the Heroku CLI. But I’ve created a little web app using the heroku.jar library (which wraps the Heroku RESTish APIs) that provides a web-based way to associate a SSH key to your Heroku account. If you don’t have an SSH key already then in Eclipse go to “Window” menu -> “Preferences” -> search for “SSH”, select the “SSH2” preferences, select the “Key Management” tab, select “Generate RSA Key…” to create a new SSH key, select “Save Private Key…”, and then select and copy the public key (starts with ssh-rsa). If you already have an SSH key then in the “Kay Management” tab select “Load Existing Key…” and copy the public key.

Now in your browser go to key.herokuapp.com, enter your Heroku username (email) & password, paste the key into the Public Key field, and click the “Add Key” button.

Step 4) Now you are ready to import the created project into Eclipse. Select the “File” menu -> “Import”, select “Project from Git”, select “Clone…”, paste the git URL into the “URI” box (you will find the git URL in the java.herokuapp.com instructions or in the email from Heroku), and select “Next”.

Eclipse will fetch the branches of the remote git repository and should display just a master branch. Select “Next” and then “Finish”. A local copy of the project will now be on your computer. Now select “Next”, select “Import as general project, select “Next”, and then select “Finish” to complete the import. From here you can take a few other steps to setup the project for local development. First, install the m2e-wtp connector, create a new Tomcat server in Eclipse, change the web module context root to “/”, and then you can just right-click on the project and select “Run As” -> “Run on Server”.

Step 5) Make a change to the app that you will be able to see when the new version is pushed to Heroku. For instance, add something to the index.jsp file. If you have setup your Eclipse for local development then you should be able to test this change locally before pushing it to Heroku.

Step 6) To commit the changes to the local git repository, right-click on the project, select “Team” -> “Commit…”, enter a commit message, and select “Commit”.

Now that the changes are in the local git repository they can be pushed to Heroku. Right-click on the project, select “Team” -> “Push to Upstream”. This will send your change to Heroku and then Heroku will run the project’s Maven build and redeploy the changes. When the process has completed you will see the details of the push and the Maven build.

Now refresh (or load) the app in your browser and you should see the changes.

That should be enough to get you started. As you dive in further check out the Heroku Dev Center for a lot more details on using Java on Heroku. Let me know if you have any questions.