A guide to building and running Greenhouse locally

Introduction

To see Greenhouse live, you may signup and use the production Greenhouse instance at http://greenhouse.springsource.org. However, we recommend getting the source code for study, adapting features of the application to your own needs, and contributing to Greenhouse development. Follow the guide below to get an embedded Greenhouse instance up and running locally.

Greenhouse Web App

To get the main Greenhouse web app up and running locally, follow the steps below:
  1. Get the source code.
  2. Import the project into the SpringSource Tool Suite (STS). Version 2.5.x or > of STS is recommended.
  3. Deploy the app by dragging 'greenhouse' over to the "SpringSource tc Server Developer Edition" instance in the Servers view.
  4. Start the server and access http://localhost:8080/greenhouse in your web browser. You'll know if it worked if you see the home page.

Greenhouse for iPhone

To build and run the Greenhouse for iPhone client locally, you will first need to install the iOS development environment, then run the project in the iPhone Simulator.

Download and Install the iOS SDK

The first step in developing iOS applications is downloading the iOS SDK package. The iOS SDK package contains everything you need to develop iOS applications, including the Xcode IDE and device simulators.

Note the download requires that you have an Apple Developer account. If you do not have one, you can register for free here.

After downloading, double click the disk image file to open it. The image contains an "About" document and the Xcode package. Double click the Xcode and iOS SDK package to begin the installation. Follow the prompts, continuing through the installation. Unless you have a good reason not to, accept the defaults for all the installation options. Once the installation is complete, you are ready to open the Greenhouse for iPhone project.

Opening the Greenhouse for iPhone Project in the Xcode IDE

Next, get the project source code.

From Finder, double click the Greenhouse.xcodeproj file to open the project in Xcode. Using the drop down menu at the top left of the Xcode window, verify that "Simulator" is selected, and "Debug [localhost]" is selected for the Active Configuration.

The Greenhouse for iPhone source code expects a instance of the Greenhouse web app to also be running locally. Verify the web app is on-line, and click the "Build and Run" button to start the app in the iPhone simulator.

Greenhouse for Android

To run the Greenhouse for Android client, you will first need to install and configure the Android SDK, and the Eclipse ADT (Android Developer Tools) plugin.

Download and Install the Android SDK

The first step in developing Android applications to download the Android SDK starter package. The starter package is not a full development environment — it includes only the core SDK Tools, which you can use to download the rest of the SDK components. Make sure to download the package that is appropriate for your development computer: Windows, Mac OS X, or Linux.

After downloading, unpack the Android SDK archive to a safe location on your machine. By default, the SDK files are unpacked into a directory named android-sdk-. Make a note of the name and location of the unpacked SDK directory on your system — you will need to refer to the SDK directory later, when setting up the ADT plugin or when using the SDK tools.

Next, add the location of the SDK's primary tools directory to your system PATH. The tools/ directory is located at the root of the SDK folder. Adding tools to your path lets you run Android Debug Bridge (adb) and the other command line tools without needing to supply the full path to the tools directory.

Install the Eclipse ADT plugin

Android offers a custom plugin for the Eclipse IDE, called the Android Development Tools (ADT). To install ADT, start the SpringSource Tool Suite, or another Eclipse distribution, then select Help > Install New Software. Then:

  1. In the Available Software dialog, click Add....
  2. In the Add Site dialog that appears, enter a name for the remote site (for example, "Android Plugin") in the "Name" field.
  3. In the "Location" field, enter https://dl-ssl.google.com/android/eclipse and click OK.

Back in the Available Software view, you should now see "Developer Tools" added to the list. Select the checkbox next to Developer Tools, which will automatically select the nested Android DDMS and Android Development Tools. Click Next. In the resulting Install Details dialog, the Android DDMS and Android Development Tools features are listed. Click Next to read and accept the license agreement and install any dependencies, then click Finish. Finally, restart Eclipse to complete the installation of the ADT plugin.

Configure the ADT Plugin

Once you've successfully downloaded ADT as described above, the next step is to modify your ADT preferences in Eclipse to point to the Android SDK directory:

  1. Select Window > Preferences... to open the Preferences panel (Mac OS X: Eclipse > Preferences).
  2. Select Android from the left panel.
  3. For the SDK Location in the main panel, click Browse... and locate your downloaded SDK directory.
  4. Click Apply, then OK.

Installing SDK Components

The Android SDK and AVD Manager is the tool that you use to install and upgrade SDK components in your development environment. The SDK package downloaded previously only contains the latest Android platform. We recommend you install all of the available platform components. To launch the tool from Eclipse/ADT, navigate to Window > Android SDK and AVD Manager, then:

  1. Select Available Packages in the left panel. This will reveal all of the components that are currently available for download from the SDK repository.
  2. Select all the available components and click Install Selected.
  3. Verify and accept the components you want and click Install Accepted. The components will now be installed into your existing Android SDK directories.

Configure an Android Virtual Device

Next, configure an Android Virtual Device for running the Greenhouse client. You can create multiple AVDs for testing, but you must configure at least one. The Greenhouse client is built using API Level 8. In order to run the app in the emulator, you will need to configure an AVD with a target of "Google 2.2 - API Level 8". To create an AVD:

  1. In Eclipse, choose Window > Android SDK and AVD Manager.
  2. Select Virtual Devices in the left panel.
  3. Click New.
  4. The Create New AVD dialog appears, and type the name of the AVD, such as "google_8".
  5. Choose the "Google 2.2 - API Level 8" target.
  6. Click Create AVD.

Installation Review

Use the following Installation Checklist to confirm you have completed all the necessary steps.

  1. Install or verify the installation of JDK 5 or 6.
  2. Install or verify the installation of Eclipse 3.4 or 3.5 or the SpringSource Tool Suite (STS).
  3. Download the Android SDK and unzip it to a safe location.
  4. Update your path or environment variable to point to the SDK location.
  5. Install the Eclipse ADT plugin.
  6. Configure the Android SDK location in the Eclipse ADT plugin
  7. Use the Android SDK and AVD Manager to download all available packages.
  8. Use the Android SDK and AVD Manager to configure one or more Android Virtual Devices (AVD).

Run the Greenhouse for Android Project

Now with the Android development environment setup, retrieve the Greenhouse for Android source code.

Import the Android project into Eclipse. The Greenhouse for Android source code comes configured to execute against a locally running instance of the Greenhouse server. Please ensure the Greenhouse web app is running locally.

Once you have a locally running Greenhouse server, select Run to start the client in the Android emulator.