OpenCDS Developer Workstation Configuration

Owned by Phillip Warner
Last updated: Jul 16, 2013Version comment
12 min read

OpenCDS Developer Workstation Configuration Instructions for OpenCDS 1.1 Release

Last updated July 15, 2013


Note:  These instructions have been verified via installations onto a Windows XP 32-bit machine and two Windows 7 64-bit machines.  If you have Windows User Access Control turned on, you may need to disable it in order to complete the installation properly.

We also have reports that OpenCDS has been successfully installed on Linux and Macintosh machines, by users who are experts in those environments.

Also note:  these instructions do not encompass setting up an Apelon DTS terminology service instance.  Setting up such an instance is not required for use of OpenCDS.  Documentation on setting up an Apelon DTS instance can be found at http://apelon-dts.sourceforge.net/. 

NOTE: we have created a common, publicly accessible Apelon DTS instance for maintaining a central set of concepts for use by the OpenCDS community.  Software to access this is included in the OpenCDS source distribution.


Installation and Setup of Infrastructure Components

Install Java

  1. Install Java SE SDK version 6 (or 7 if you are comfortable updating the POM files for Maven)
    1. Download appropriate 32-bit or 64-bit Java SE SDK from http://www.oracle.com/technetwork/java/javase/downloads/index.html.
      1. Current Maven POM configuration files expect Java 1.6.  Experts may wish to use Java 1.7 and make appropriate changes to the POMs.
    2. Run executable, install using default options
      1. You can use a non-default installation directory if desired
    3. Control Panel → System → Advanced → Environment Variables → System Variables
      1. Set JAVA_HOME to Java SE SDK location
        1. E.g., C:\Program Files\Java\jdk1.6.0_26
      2. Add %JAVA_HOME%\bin to Path
        1. In this example, was added to beginning of Path

Install Maven

  1. Download .zip file of latest stable Maven build from http://maven.apache.org/download.html
    1. These instructions have been tested for both Maven 3.0.3 at http://www.apache.org/dyn/closer.cgi/maven/binaries/apache-maven-3.0.3-bin.zip and Maven version 2.2.1 at http://www.apache.org/dyn/closer.cgi/maven/binaries/apache-maven-2.2.1-bin.zip
    2. Unzip archive
    3. Follow instructions in README.txt, provided below
    4. Directory specifications below are not mandatory, but recommended for consistency purposes
      1. Place unzipped folder (apache-maven-3.0.3) in following directory: C:\Program Files\Apache Software Foundation
    5. Control Panel → System → Advanced → Environment Variables → System Variables
      1. Set MAVEN_HOME to “C:\Program Files\Apache Software Foundation\apache-maven-3.0.3”
      2. Add %MAVEN_HOME%\bin to Path
        1. In this example, was added to beginning of Path

Install Apache CXF

  1. Download latest binary version of Apache CXF from http://cxf.apache.org/download.html
    1. Unzip and move the apache-cxf-2.X.X folder to be under C:\Program Files\Apache Software Foundation

Install Tortoise SVN

  1. Download TortoiseSVN from http://tortoisesvn.net/downloads.html
    1. Note: if you already have TortoiseSVN installed, get the latest version if you plan to update Subclipse (the Eclipse Subversion plugin) to the latest version.  You may run into some problems when using TortoiseSVN to check out the OpenCDS project if TortoiseSVN uses a Subversion version that is older than the Subversion version used by Eclipse.
    2. Install using default options, then restart machine

Install Tomcat

  1. Download latest Tomcat using “32-bit/64-bit Windows Service Installer” from relevant download page at http://tomcat.apache.org/
    1. OpenCDS has been tested using both Apache Tomcat versions 6 and 7, you can use either
    2. Accept defaults
    3. Installation directory may be changed if desired
    4. Set Tomcat Administrator Login to something secure
      1. You may even prefer to remove the administrator login if you have physical access to the server.
  2. Control Panel → System → Advanced → Environment Variables → System Variables
    1. Set CATALINA_HOME to, e.g., “C:\Program Files\Apache Software Foundation\Tomcat 7.0”
    2. Add %CATALINA_HOME%\bin to Path
      1. In this example, was added to beginning of Path

Install Latest Stable Version of Eclipse

  1. Download Eclipse from http://www.eclipse.org/downloads/
    1. Compatibility note:  as of 11/8/2011, the JBoss Drools Eclipse Workbench is not available as a stable release for Eclipse version 3.7.X (Eclipse Indigo).  Therefore, it is recommended that Eclipse Helios (version 3.6.X) or newer Eclipse is used instead.
      1. Update as of 11/14/2012: the above issue is no longer a problem
    2. In this example, installed Eclipse Helios version 3.6.2 from http://www.eclipse.org/downloads/packages/release/helios/sr2
    3. Select 32 or 64-bit version, whichever is appropriate for your machine/OS.
  2. Create an Eclipse instance by unzipping the zip archive into a directory of choice
    1. NOTE: if you already have eclipse installed (e.g., at C:\Program Files\eclipse) for other projects you are working on, we strongly recommend that you install eclipse in a different directory (e.g., C:\Program Files\eclipseOpenCDS).  This way, you will not impact any existing code or Eclipse settings (e.g., with regard to plugins).  Furthermore, in the event that you need to uninstall and reinstall OpenCDS, you will be able to delete the OpenCDS eclipse folder without impacting any other projects.

    2. The default directory used for these instructions is C:\Program Files\eclipse, which is where the Eclipse instance will be created if you unzip the zip archive directly into C:\Program Files

  3. Notes
    1. You do not need to modify your path or add environment variables to use eclipse
    2. Read the release notes (especially if you have problems) found at C:\Program Files\eclipse\readme\readme_eclipse.html
    3. Remember that you can often fix weird problems in eclipse from a command prompt by running “eclipse –clean” which will start eclipse with a clean slate (and make it forget all the in-process state of files you were currently working on)
  4. Create a shortcut for Eclipse that passes in Java Virtual Machine parameters that a) ensures that the JDK is used rather than the JRE and b) ensures sufficient memory is allocated.  Then, use the shortcut for launching Eclipse.  Different shortcuts can be created if different Eclipse configurations are desired.

    1. E.g., edit target of shortcut to:

      "C:\Program Files\eclipse\eclipse.exe" -vm "C:\Program Files\Java\jdk1.6.0_26\bin" -vmargs -Xmx900m




    2. Alternatively, the

      C:\Program Files\eclipse\eclipse.ini

      can be edited.

      1. For more information, see

        http://wiki.eclipse.org/FAQ_How_do_I_increase_the_heap_size_available_to_Eclipse%3F,

        http://wiki.eclipse.org/Eclipse.ini.

  5. When first starting Eclipse, set workspace to appropriate directory

    1. Suggested location is “C:\OpenCDS”

    2. An alternate suggested location if installing multiple versions of OpenCDS on the same machine is “C:\OpenCDS_[version]”

      1. e.g., “C:\OpenCDS_v1.0_preview”, “C:\OpenCDS_alpha”, “C:\OpenCDS_v1.1.2”, etc.

Install Eclipse plugins

Eclipse has built-in tools to locate and install plug-ins, and to update them when necessary.  Use the built-in tools whenever possible. 

 

There are two ways to do this.  The new method is called Eclipse Marketplace.  Use it whenever you can by going to

Help → Eclipse Marketplace

The traditional method is more tedious, and will need to be used if you can’t find the software you are looking for in the Eclipse Marketplace.  It is also used for some plugins that don’t install all the required options when run from the Marketplace menu.  This method is used by going to

Help → Install New Software

 

    1. Install M2Eclipse
      1. Before you can use Maven from Eclipse, you will need to make sure that you are running Eclipse from the JRE that is part of a JDK virtual machine.  One safe way to do this is to create a shortcut for running Eclipse, and adding the path to the JDK in the shortcut target, as described above under the Eclipse installation instructions.
      2. From Eclipse Marketplace – DO NOT DO THIS!  You will need to do the initial install the traditional way, as described next (the Eclipse Marketplace does not currently allow you to do a base install of m2eclipse)…
      3. From Install New Software
        1. Help → Install New Software


        Type just the URL (http://m2eclipse.sonatype.org/sites/m2e) (1), click the Add button (2), type in “m2eclipse” for the name, and hit “okay” for adding the repository.  You should then click in the box beside “Maven Integration for Eclipse (3), and click the Next button at the bottom of the Install window.

        It will verify your selection (making sure dependencies are present), and then give you a chance to go back to add dependencies, or continue by clicking Next

        Accept the license and click Finish.

        Restart Eclipse if prompted.

        If you get the following warning, click OK to ignore


        If you get the following error, restart the machine and try again.



    2. Make sure Eclipse is pointed to a JDK rather than a JRE in Eclipse Preferences (Windows → Preferences → Java → Installed JREs and Windows → Preferences → Java → Installed JREs → Execution Environments)



    3. Install Subclipse
      1. From Eclipse Marketplace:  DO NOT DO THIS!  It installs correctly, but is missing some important functionality.
        1. UPDATE:  The install from Eclipse Marketplace has apparently been fixed.
      2. From Install New Software
        1. Select all options from the menu after you enter / select the path as shown below
          1. URL = http://subclipse.tigris.org/update_1.8.x
          2. Name = anything; suggest “Subclipse”


        3. Click on Next
          1. It will verify your selection (making sure dependencies are present), and then give you a chance to go back to add dependencies, or continue by clicking Next.
        4. Accept the license and click Finish
        5. If you get the following warning, click OK to ignore.


        6. Restart Eclipse if prompted
    4. Set Eclipse Preferences for Subversion
      1. Window → Preferences → Team → SVN
      2. Select a client for the SVN Interface
        1. If no clients are listed, you probably installed Subclipse from the Marketplace, and didn’t get the client.  Go back to the step about installing Subclipse and get the client.
        2. For this example, JavaHL is selected
      3. Window → Preferences → Team → SVN → Menu icons
        1. Select Tortoise SVN
    5. Set up Tomcat Server in Eclipse
      1. File → New → Other → Server → Server
        1. Select Apache Tomcat (e.g., Tomcat 7.0) and use default settings
      2. Select installation directory, Finish
    6. Set Eclipse Preferences for Maven

      1. Window → Preferences → Maven → Installations → Add → specify Maven root folder (e.g., C:\Program Files\Apache Software Foundation\apache-maven-3.0.3) → OK


      2. Create a settings.xml file in location specified in Eclipse under Window → Preferences → Maven → User Settings


      3. Sample XML (used for this example):

        <?xml version="1.0" encoding="UTF-8"?>
        <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0http://maven.apache.org/xsd/settings-1.0.0.xsd">
        <pluginGroups>
               </pluginGroups>
               <proxies>
               </proxies>
               <servers>
               </servers>
               <mirrors>
               </mirrors>
               <profiles>
               </profiles>
        </settings>
      4. Restart Eclipse
      5. Update central Maven repository index, as follows.  Note that if you don't do it here, it will automatically take place later in the installation process.  We recommend updating the index here, so that if there is an error, it is clear where the error occurred.
        1. Windows → Show View →Other → Maven → Maven Repositories
          1. Click Global Repositories → right click "central", select Update Index
          2. This may take a while; you can track progress by clicking on the progress icon on the bottom right of the screen  ()
          3. Sometimes, it takes multiple attempts before this completes.  You may need to restart Eclipse in the process.
          4. If you see an error message of "Unable to update index for central," it may mean you need to turn off a Proxy connection (see http://www.ehow.com/how_6079770_using-proxy-server.html) or configure Proxy-based Maven connections (see http://maven.apache.org/guides/mini/guide-proxies.html).  Once you have made the changes, verify that you do not get this error by repeating the steps above.
    7. InstallJbossDrools Eclipse Workbench (allows writing Drools rules and working with Drools Flow, and testing / debugging directly from Eclipse; part of JBoss Tools).
      1. Automatic installation from Eclipse
        1. Download Drools plugin for Eclipse
          1. Help → Install New Software
          2. Use appropriate URL found at http://www.jboss.org/tools/download.html.  In this case, use http://download.jboss.org/jbosstools/updates/stable/helios/
          3. Name used in this example for repository: Drools
          4. Install the three Drools components indicated below under the SOA Development category


          5. If you get the following warning, click OK to ignore.


          6. Restart Eclipse if prompted
      2. Download the Drools Runtime version 5.5.0.Final
        1. Download file named Drools Binaries from http://www.jboss.org/drools/downloads.html, using link at
          http://download.jboss.org/drools/release/5.5.0.Final/drools-distribution-5.5.0.Final.zip
        2. Place contents of the binaries folder in the zip archive into a directory (C:\Data\Drools\Drools5.5.0.Final is used in this guide)
        3. E.g., this directory should look like the following:
      3. Configure Drools Eclipse Workbench
        1. Windows → Preferences → Drools → Installed Drools Runtime → Add
          1. Add the version of Drools (since you are allowed to have more than one installed) that you want to add to the build path of newly created Drools projects (the example below shows an older version, you should use the current version of Drools that you have just installed).
        2. Select the Drools runtime for use (Use the current version, not 5.3 as shown below)


        3. Restart Eclipse

 

OpenCDS Configuration in Eclipse

All OpenCDS sub-projects are contained within a parent project called “opencds-parent”.  An overview of these sub-projects will be made available in a separate document in the near future.

Import Projects into Eclipse

  1. Add the OpenCDS repository to the list of repositories available to Eclipse.
    1. Window → Show View → Other…→ SVN → SVN Repositories


    2. You will see a list of the configured Subversion repositories (your initial list may be empty).  Right-click on the list and choose New → Repository Location from the pop-up dialog


    3. Add the repository for the OpenCDS Trunk Project.  The relevant URLs are as follows.  Most individuals should initially connect to the 1.x release repository.

      1. E.g., enter http://develop.opencds.org/svn_v1.0/trunk/opencds-parent, and click on Finis

        RepositoryURL and DescriptionAccess
        Main development trunk

        http://develop.opencds.org/svn_active/trunk/opencds-parent

        Locus of the active development on 1.x releases.

        		Currently restricted to active code contributors.  Access may be requested from David Shields at david.shields@opencds.org.
        1.x release

        http://develop.opencds.org/svn_v1.0/trunk/opencds-parent

        Stable snapshots from the main development trunk.

        		Public read-only access.  ID and password not required.
  2. Import the OpenCDS Project Step 1: Establish Maven Projects
    1. Close Eclipse if open
    2. Check out OpenCDS parent project into the Eclipse OpenCDS workspace as follows:
      1. Go to workspace location (e.g., C:\OpenCDS)
      2. Right click and select SVN Checkout from context menu


      3. Enter URL of repository and proceed, as noted below.  Note that the URL of the repository should be the appropriate one noted in the table above.  Also note that you must add “opencds-parent” to the end of the Checkout directory.


      4. Now, build the project with Maven from the command line
        1. From the command line, go to the opencds-parent folder in the workspace (e.g., C:\OpenCDS\opencds-parent)
        2. Run the command
          1. mvn clean
        3. Run the command
          1. mvn install
        4. Run the command
          1. mvn eclipse:eclipse
          2. running this command creates all the Eclipse-specific project settings for OpenCDS so that you can work with it in Eclipse.
  3. Import the OpenCDS Project Step 2: Import Maven Projects
    1. Open Eclipse
    2. Import the OpenCDS parent project into Eclipse OpenCDS workspace as a Maven project, as follows:
      1. File → Import → Maven → Existing Maven Projects → Next


      2. Root Directory → Browser → opencds-parent location (e.g., C:\OpenCDS\opencds-parent).  Select all Projects, Finish (the latest version of OpenCDS may have slightly different modules than those shown in the example below)


Build OpenCDS Eclipse Project

  1. Following the process above, you should see something similar to the following in Eclipse as built projects (there are more modules as time goes on, and some get renamed as well):

    1. A build has already taken place from the command line as a part of the setup process.  For future builds, you can do through the following procedure:\
      1. Right click on opencds-parent → Run as → Maven Clean
      2. Right click on opencds-parent → Run as → Maven Install


Troubleshooting

Maven is great when things are working.  However, it can be challenging to get things to work when Maven is not working.  The most common problem will look something like this:

Here are a couple suggestions to fix the problem:

  1. Check the results of the Maven Installs

    Maven will sometimes report a successful installation when the specified file (the “-Dfile=…” parameter) does not exist.  This will then cause downstream failures of Maven builds.  Verify that the local Maven repository contains the jar files you installed by looking in your local Maven repository (found as a folder named “.m2”  in your “User” directory).  For example, this path for the SpringSource jar will be:

    .m2\repository\org\apache\jasper\springsource\com.springsource.org.apache.jasper.org.eclipse.jdt.springsource\6.0.20.S2-r5956\com.springsource.org.apache.jasper.org.eclipse.jdt.springsource-6.0.20.S2-r5956.jar


    If you find that one of the jars that you installed with a “mvn install …” command is missing, then rerun the installation, making sure that you have used the correct path for the source file, and spelled everything correctly.  The most common error is to download the files to the default download path on your machine (eg, “C:\yourUserName\Downloads”), but to install it using the sample command that we furnished which has a different path.  Another common problem is that the downloaded package might have a “.zip” extension, and needs to be changed to a “.jar” extension before use.

  2. The nuclear option

    If you cannot get things to work using the above approach (usually due to a Maven issue), you can reset your system to the state just prior to the Eclipse installation (section I.F) via the following:

    -    Delete Eclipse folder (e.g., C:\Program Files\eclipse)

    -    Delete OpenCDS workspace (e.g., C:\OpenCDS)

    -    Delete Maven repository (e.g., C:\Users\Ken\.m2)

    You can then re-attempt the installation and configuration process.

Document Version History

  • 8/28/2011
    • Created by Kensaku Kawamoto based on configuration instructions for OpenCDS alpha release
    • Changes include:
      • Use of Drools and Guvnor 5.2 instead of 5.1.1
      • More information on 64-bit OS configuration
      • Use of newest releases of software components
  • 11/8/2011
    • Updated by Kensaku Kawamoto, with verification on 32-bit and 64-bit Windows OSs
    • Use of Drools 5.3.0 instead of 5.2.0
  • 11/9/2011
    • Updated by Kensaku Kawamoto to include use of SilkSVN for 32-bit OSs as well
  • 11/10/2011
    • Updated by Kensaku Kawamoto to note need to use latest Tortoise SVN version
  • 11/16/2011
    • Updated by Kensaku Kawamoto to include preliminary Guvnor/Designer installation instructions and to make additional note regarding Tortoise SVN
  • 11/29/2011
    • Updated by David Shields to include solution to failed installation of JBoss Application Server in a path including “Program Files (x86)”.
  • 12/16/2011
    • Updated by David Shields to include alternate installation paths, 2.0  version of JBoss Designer, alternate ports for JBoss, and availability of OpenCDS 1.0 binaries.
  • 12/17/2011
    • Updated by David Shields to include information on extended default timeout for JBoss AS 7.0.2
  • 11/14/2012
    • Major update by David Shields to reflect latest versions of all components, including Drools 5.4, JBPM Designer 5.3, and JBoss 7.1.x
  • 1/11/2013
    • Updated to reflect Drools 5.5, Designer 5.4
  • 5/24/2013
    • Updated to move Guvnor installation instructions to separate document