Development Environment Setup

Introduction

This page describes the steps for configuring the ThreadFix development environment under Windows and OS X. Linux environment setup has not been tested with these steps, but should be similar to OS X.

Setup and Configuration

Downloads

To compile ThreadFix, download and install the following dependencies:

• Java JDK 7: ThreadFix currently does not support Java 8. Be sure to download the Java 7 JDK. This guide was written with 64-bit Java, but 32-bit Java should also work.
• Apache Tomcat 7: Download.
• Maven: Download.

It is recommended that you download and install one of the following IDEs, as it will simplify compilation and development:

• IntelliJ IDEA, Ultimate Edition: The Community Edition of IntelliJ IDEA does not support web development, and will not work with these instructions. Download/Purchase.
• Spring Tool Suite: Download.

Cloning the Git repository

From the command line (using Git bash in Windows, if necessary), run the following command:

git clone https://github.com/denimgroup/threadfix.git

This will create a directory named threadfix in the current directory that contains ThreadFix source code.

IntelliJ IDEA Setup Instructions

1. Import the ThreadFix project.

   1. From the "File" menu, select, "Import Project".
   2. Navigate to the root threadfix directory, and select pom.xml.
   3. Click "Next" on the first two pages.
   4. On the Java SDK page, select the JDK that you downloaded earlier. If Java 7 JDK does not appear as an option, click the green "+" button in the top-left corner, and add a new JDK. You will need to select the location where you installed Java 7. Finally, click, "Next".
   5. Set the project name and path, then click, "Finish".

2. Configure the Tomcat deployment.

   1. From the "Run" menu, select, "Edit Configurations."
   2. Create a new Local Tomcat Server.
   3. Click the "Configure" button to the right of the Application Server dropdown.
   4. Create a new Tomcat application server, and set Tomcat Home to the location where you installed Tomcat. Click "OK".
   5. Select the Tomcat application server you just configured in the Application Server dropdown.
   6. In the "Deployment" tab, add the threadfix:war artifact, and set the Application Context to /threadfix.

3. Configure the database.

   1. Open the src/main/resources/jdbc.properties file, located in the threadfix-main module.
   2. Change the hibernate.hbm2ddl.auto property to "create".

4. Starting the server.

   1. From the "Run" menu, select, "Run...".
   2. Select the Tomcat application server you created earlier. IntelliJ will compile and deploy ThreadFix.

Spring Tool Suite Setup Instructions

1. Import the ThreadFix project.

   1. Click "File/Import..." and select "Maven / Existing Maven Projects".
   2. Click "Next".
   3. Select the threadfix directory.
   4. Leave all of the check boxes selected, and click "Finish".

   You will see a bunch of errors. These errors will be resolved in the next steps.

2. Ignore maven plugins

   1. Create a file named lifecycle-mapping-metadata.xml with the following contents:

   <?xml version="1.0" encoding="UTF-8"?>
   <lifecycleMappingMetadata>
     <pluginExecutions>
       <pluginExecution>
         <pluginExecutionFilter>
           <groupId>org.codehaus.mojo</groupId>
           <artifactId>buildnumber-maven-plugin</artifactId>
           <goals>
             <goal>create-timestamp</goal>
           </goals>
           <versionRange>[0.0,)</versionRange>
         </pluginExecutionFilter>
         <action>
           <ignore />
         </action>
       </pluginExecution>
   
       <pluginExecution>
         <pluginExecutionFilter>
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-jar-plugin</artifactId>
           <goals>
             <goal>jar</goal>
           </goals>
           <versionRange>[0.0,)</versionRange>
         </pluginExecutionFilter>
         <action>
           <ignore />
         </action>
       </pluginExecution>
   
       <pluginExecution>
         <pluginExecutionFilter>
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-dependency-plugin</artifactId>
           <goals>
             <goal>list</goal>
           </goals>
           <versionRange>[0.0,)</versionRange>
         </pluginExecutionFilter>
         <action>
           <ignore />
         </action>
       </pluginExecution>
   
       <pluginExecution>
         <pluginExecutionFilter>
           <groupId>org.zeroturnaround</groupId>
           <artifactId>jrebel-maven-plugin</artifactId>
           <goals>
             <goal>generate</goal>
           </goals>
           <versionRange>[0.0,)</versionRange>
         </pluginExecutionFilter>
         <action>
           <ignore />
         </action>
       </pluginExecution>
   
       <pluginExecution>
         <pluginExecutionFilter>
           <groupId>org.codehaus.mojo</groupId>
           <artifactId>gwt-maven-plugin</artifactId>
           <goals>
             <goal>compile</goal>
           </goals>
           <versionRange>[0.0,)</versionRange>
         </pluginExecutionFilter>
         <action>
           <ignore />
         </action>
       </pluginExecution>
   
       <pluginExecution>
         <pluginExecutionFilter>
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-dependency-plugin</artifactId>
           <goals>
             <goal>copy-dependencies</goal>
             <goal>unpack</goal>
           </goals>
           <versionRange>[0.0,)</versionRange>
         </pluginExecutionFilter>
         <action>
           <ignore />
         </action>
       </pluginExecution>
   
     </pluginExecutions>
   </lifecycleMappingMetadata>

   2. Open File / Preferences (Clover + , on OS X) of STS
   3. Expand Maven on the left panel
   4. Click "Lifecycle Mappings"
   5. Hit Browse under "Change mapping file location"
   6. Select the lifecycle-mapping-metadata.xml file you saved in step 1
   7. Click OK

3. Compile and download dependencies.

   1. Right click the master-pom project and select Maven | Update Project.
   2. In the dialog that pops up, click "OK" and wait for the workspace to build.

4. Configure the database.

   1. Open the src/main/resources/jdbc.properties file.
   2. Change the hibernate.hbm2ddl.auto property to "create".

5. Configure the Tomcat deployment.

   1. In the Server window on the bottom left, click "No servers are available. Click this link to create a new server..."
   2. Select "Apache / Tomcat v7.0" server, and click "Next".
   3. Select the directory where Tomcat is under "Tomcat Installation Directory". Then, click "Next".
   4. Select threadfix(threadfix-main) from the list on the left. Click, "Add".
   5. Click, "Finish".
   6. Select the Tomcat server and click the play button in the server panel.

Running ThreadFix Without an IDE

If your goal is to just get the latest build of ThreadFix running, and setting up a development environment is not a priority, you can run a Maven command to do so.

1. Open a terminal or a command prompt and navigate into the directory of the ThreadFix project that you cloned.
2. Run the following command: mvn clean install -P devTomcat

Note: if you wish to run ThreadFix on a different port than the default 8080 add the following parameter to your mvn command.

-Dcargo.servlet.port=<Port>

This will get you a basic build of the ThreadFix project. If you're familiar with Maven you'll notice that we included the devTomcat profile. This profile starts a tomcat instance for ThreadFix to run on. There exist two other profiles that would be useful to run in conjunction with the devTomcat profile.

hsqldb

The hsqldb profile ensures that your instance of ThreadFix is running on an HSQL database instance. This profile copies a database properties file into the build directory during build time that includes the correct connection properties to an HSQL database.

mvn clean install -P devTomcat,hsqldb

mysql

The mysql profile ensures that your instance of ThreadFix is running on a MySQL database instance. You must first make sure that you have a MySQL instance set up on your machine. This profile copies a database properties file into the build directory during build time that includes the correct connection properties to a MySQL database.

mvn clean install -P devTomcat,mysql

To learn more about Maven build profiles, check out the official Maven documentation here.

Post-Configuration

Log in and edit the user accounts

In a web browser, navigate to

http://localhost:8080/threadfix/login.jsp

If you don't see a login screen with the ThreadFix logo, something went wrong.

Try to log in with the credentials:

• Username: user
• Password: password

If you don't get an error message, then your database is also set up correctly and you have set up ThreadFix correctly. The first item of business is to delete the "user" account and create one for yourself and anyone else who is using the system. To add a new user, click the “Configuration” link in the header bar, then “Manage Users,” then “Add User,” pick a name and password, and submit the form. To delete the user “user”, click the “Configuration” link in the header bar, then “Manage Users,” then the name in table “user,” then “Delete."

For more discussion on user management, see the PermissionsSystem article.

Getting Started link

Here's the Getting Started Guide. Skip to the Demo header to skip the package configuration section.

Good luck! Please log any bugs to the GitHub issue tracker: https://github.com/denimgroup/threadfix/issues?state=open

And please join the ThreadFix Google Group to post issues and request technical support: https://groups.google.com/forum/#forum/threadfix