Documentation Home
Time will vary depending on connection speed, etc.
This will take
15 mins.

Eclipse IDE Setup


One of the best ways to get started with Broadleaf is to import the Heat Clinic into your favorite Java IDE. This will make editing code easier and also give you the ability to hook up a debugger to inspect code execution paths. You might not want to tie the execution of the Heat Clinic to the lifecycle of your IDE and instead run it from the command line. See the docs on running the Heat Clinic from your CLI.

  • Importing the Heat Clinic into your favorite IDE and running it via the command line or through the IDE
  • Hooking up a debugger to start inspecting code execution paths
  • Adding new code to the project


Install the required software for the Heat Clinic

We recommend completing the running the Heat Clinic from your CLI tutorial prior to completing this tutorial.


If you don't already have it, download the latest version of Eclipse Mars IDE for Java EE Developers. We recommend using Eclipse Mars SR2 (the latest).

While this tutorial is written with the assumption of Eclipse Mars and that is what we officially recommend, Eclipse Luna will likely also work as most of the setup tasks should be the same. The only exception is that you might have to manually install the m2eclipse plugin from the Eclipse Marketplace

Once you have Eclipse installed, you should be sitting at a blank workspace that looks like this:

Check that Eclipse knows about the Java 8 JDK

Once Eclipse is downloaded and installed (or if you are using an existing Eclipse installation), you should verify that you have a Java 8 JDK.

Open the Eclipse Preferences pane and navigate to Java -> Installed JREs. You should see an entry for Java SE 8 in the list:

In the above example, I have a few different installed JREs installed, but Java SE 8 is on the list and is the default JDK (Java 8 does not need to be the default JDK, just has to be in the list).

Add the Java 8 JDK to Eclipse

If you do not see Java SE 8 in the list, then you need to let Eclipse know about this JDK. Hit the 'Add...' button on the right of the 'Installed JREs' preferences pane. You should now be presented with this:

In the 'JRE home' input, put the environment variable for JAVA_HOME that you set up in the running the Heat Clinic from your CLI tutorial. After adding the path you should see the JRE system libraries appear below:

Now you are all set to import the Heat Clinic into your workspace!

Import the Heat Clinic project

Now you need to import the Heat Clinic demo site into your workspace from the location that we saved the project to when we downloaded it.

  1. Go to File -> Import...
  2. Expand the "Maven" folder, highlight "Existing Maven Projects" and hit "Next"
  3. In the box for "Root Directory" enter the path to the directory that you saved your Heat Clinic DemoSite to on your filesystem, or hit the "Browse..." button next to the input box to browse for the location. If you type the path in manually, you might need to hit the 'Refresh' button on the right-hand side. After you do that, you should now see 4 different projects pop up
  4. Note that there is a checkbox for "Add project(s) to working set" and the value is defaulted to 'ecommerce-website'. Working sets will be come important later, but we can leave this like it is for now
  5. Hit the 'Finish' button on this dialog box to finish the import

It might take a bit to complete as Eclipse downloads all of the Maven dependencies necessary for Broadleaf. You will know it is done importing by activity on the bottom-right corner of your screen. If you cloned the project from GitHub, you might also see an 'Auto share git projects' dialog box as well.

Once the import process has finished, your workspace should look like this:

You should have 4 projects in your installation:

  1. DemoSite - the "Maven parent" that the other projects are children of. This is not a Java project on a Java build path
  2. admin - the Broadleaf backend application for managing the catalog, content, offers, etc. Builds into a .war file
  3. core - common module shared between the site and admin projects, used for common utilities, services, database tables, etc
  4. site - the Heat Clinic frontend. Contains all of the styling and user interactions for the Heat Clinic as seen on

Now that the project is imported, right-click on the root project (which should be called DemoSite or ecommerce-website) and go to Maven -> Install:

This will fully compile and build the Heat Clinic application. Once this is completed, you now have 2 options:

  1. Use the command line to control Tomcat (recommended)
  2. Run the project from within Eclipse

Additional recommended setup

Working Sets

In order to properly organize these projects within Eclipse, we highly recommend splitting out the projects into distinct working sets. Since the "Maven parent" project (that just contains a root pom.xml without much else) also contains all of the subprojects (admin, core, site), this means you will get duplicates if you try to do things like open resource. You can see this if you type cmd+shift+r (on OSX) or ctrl+shift+r (on Windows) and then type ProductController in the popup:

You'll notice that I have 3 instances of ProductController shown here in my view. The 3rd item in the list is the "correct" one, meaning that is the one that is within a project on a Java build path and that Eclipse will pick up as a Java file. We want the other 2 items out of our view. The way to achieve this is to split the projects into 2 working sets: 1 with just the top level project in it, and 1 with the 3 Java projects inside of it.

To configure your working sets:

  1. At the top of the "Project Explorer" page, hit the down arrow carrot towards the right to bring up a dialog that contains "Select Working Set..."
  2. On the new dialog, click the 'Selected Working Sets' radio button, highlight the "ecommerce-website" working set (by clicking on it) and then hit the 'Edit...' button on the right
  3. A new window will pop up referencing the 'ecommerce-website' working set. It will look something like this: Change this screen such that the admin core and site projects are the only ones checked. When you are done hit 'Finish'. The final result should look like this:
  4. Once back at the 'Select Working Set' dialog, hit the 'New' button on the right to create a new working set
  5. Select the 'Resource' working set type and hit 'Next...'
  6. For the working set name enter "Maven Top Level" and select the 'DemoSite' project since that will be the only project in this working set, then hit "Finish"
  7. You should now have 2 working sets. Make sure they are both 'checked' by clicking on the checkbox to the left of the names. The final result should look like this; when you're done, hit 'OK':
  8. Select the down-caret again but this time go to 'Top Level Elements' and click on 'Working Sets'
  9. And in your 'Project Explorer' you should now see the view organized by working set:

Now we need to hide the 'Maven Top Level' working set from the 'Open Resource' and 'Open Type' views:

  1. Bring up the 'Open Resource' dialog with ctrl+shift+r on Windows and Linux or cmd+shift+r on OSX, then click on the black down-caret on the top right, then click on 'Select Working Set':
  2. Click on the checkbox next to 'ecommerce-website' and then hit the 'OK' button:

Now if you type 'ProductController' in the dialog, you only get a single result!

Use Eclipse's embedded Tomcat

You might be used to running Eclipse's embedded Tomcat instance available in the "Servers" view. This documentation is coming soon.