This section will help the onboarding process of new developers by providing lists of access and permissions you'll need, how to set up your development environments, how the production environment is set up and how you will go about submitting your changes to the StarExec repository.

Access Requirements

Below is a list of accounts and permissions you'll need and who can grant them to you.

Development Environment

We have two development environments that we use. The first is local to our own machines. We can do a lot of database and Java development off of the cluster and make changes locally. Each person also has the ability to host a cluster development environment which consists of your own Tomcat instance and database. This allows us to test the application in an environment as close to the production environment as possible. This also allows us to actually test things with the full cluster such as job distribution, etc. Each developer is responsible for setting up their own cluster environment however they see fit.

Local

Please note this software is not required for local development, it's just how we happen to have set things up for ourselves. You are more than welcome to use different tools etc. as long as it doesn't conflict with the repository and the structure of the project.

1. Install Software
   1. Eclipse EE (optional)
      Install Eclipse Helios Service Release 1
      (Note: Eclipse Indigo will work, but some of the following settings will be named differently)
   2. Apache Tomcat
      Download version 7.0.4 of Apache Tomcat and extract it where you installed Eclipse EE
   3. MySQL
       At least version 5.5.6 is needed, for some features (LIMIT statements with procedure parameters) we use in our procedures.  Install the latest version of MySQL Community Server . Remember the root username and password for later.
   4. JDBC Connector
      Download the latest version of the MySql JDBC driver
      Extract the jar to Tomcat's lib folder. This is located wherever you extracted Tomcat. (Such as C:\Program Files\Eclipse EE\apache-tomcat-7.0.4\lib)
   5. Git
      Install a subversion client. You can use the command line or a tool such as GitHub Desktop
2. Configure MySql
   MySql needs to be configured to work properly with StarExec. This basically means you need to import our database schema into your instance of MySQL.
   1. Open a command prompt
   2. Change your directory to the location of the starexec project you checked out from SVN (see 3a iii in these instructions)
   3. Within the starexec project directory change directories to starexec\sql
   4. In the sql directory, confirm you see a file called NewInstall.sql
   5. Recall your MySQL root password and run the command mysql -u"root" -p"password" < NewInstall.sql
   6. To populate the database with sample data run mysql -u"root" -p"password" < NewInstall.sql
   7. You should see no output if there wasn't an error

   8. Confirm the database was created by checking for tables and a description of an arbitrary table:

      mysql -u"root" -p"password"
      USE starexec;
      SHOW TABLES;
      DESCRIBE users;
      

   9. It is recommended you create a separate user for your database to mirror the permissions the starexec production app is running under. To do that locally, execute the following SQL commands with the desired USERNAME and PASSWORD when logged in as root

      CREATE USER 'USERNAME'@'localhost' IDENTIFIED BY 'PASSWORD';
      GRANT ALL ON starexec.* TO USERNAME@'localhost';
      

3. Configure Eclipse (if you are using Eclipse for an IDE)  
   1. Import StarExec
      You may need to import the StarExec project you pulled down from SVN into your workspace. The project in the repository is a Dynamic Web Application project, which you cannot directly import to Eclipse, so we have to work around this...
      1. Go to File > New > Other... then type in dyn in the search bar and select Dynamic Web Project and hit Next
      2. Enter starexec as the project name and make sure the Target runtime is Apache Tomcat v7.0 [you may need to look at 3b at this point to finish this part] and hit Finish
      3. [link no longer works???]Now on your desktop or in some temp folder do an SVN checkout from https://svn.divms.uiowa.edu/repos/clc/projects/starexec/dev/branches/fb1/starexec
      4. Copy everything from you checked out of the repo (desktop/starexec/) into the starexec dynamic web project you just created (workspace/starexec/). Replace everything if prompted.
   2. Setup Tomcat
      Eclipse needs to know where you installed Tomcat.
      1. Go to Window > Preferences
      2. Type in server in the search box
      3. Select Runtime Environments under the server node
      4. Click the Add... button
      5. Under the Apache folder select Apache Tomcat v7.0
      6. Check the Create a new local server option
      7. Click Next and leave the name field as whatever the default is
      8. For Tomcat installation directory click Browse and point to the folder that was created when you extracted Tomcat
      9. Hit Finish
      10. Add Apache's libraries to the project
          1. In Eclipse, right click the starexec project and hit Properties
          2. Type build in the search window and click Java Build Path
          3. If you see Apache Tomcat v7.0 in the list in the Library tab, you skip the rest of the steps in this section
          4. Click Add Library and select Server Runtime
          5. Hit Next and select Apache Tomcat v7.0 and hit Finish and Ok until all dialogs are closed
             Now that Eclipse can see tomcat and you have a local server, we need to configure the local server to match the production server configuration.
4. Configure tomcat
   1. Security Realm
      We need to set up security realms for your local tomcat server to enable form based login. You essentially have to tell Tomcat how your database is set up so it can perform authentication for us.
      1. Open your local Server.xml file. If you are using Eclipse, this file should be located in your project workspace under a special Servers directory and within another folder containing your server's name. For example mine is: \Eclipse EE\Servers\Tomcat v7.0 Server at localhost where EclipseEE is my Eclipse workspace.  If you are working directly with Tomcat (no Eclipse), then you can find servers.xml in the conf/ subdirectory of the tomcat directory.

      2. The default servers.xml file has a "lockout" Realm controlling access to the Manager Application for tomcat.  You can add the following <Realm> as a subrealm of this existing one  in your Server.xml (or servers.xml) file, where USERNAME and PASSWORD are the username and password you established above for the starexec database on your MySql installation. 

         <Realm className="org.apache.catalina.realm.LockOutRealm">
             <Realm className="org.apache.catalina.realm.JDBCRealm"
                 driverName="com.mysql.jdbc.Driver"
                 connectionURL="jdbc:mysql://localhost/starexec"
                 connectionName="USERNAME"
                 connectionPassword="PASSWORD"
                 userTable="users"
                 userNameCol="email"
                 userCredCol="password"
                 userRoleTable="user_roles"
                 roleNameCol="role"
                 digest="SHA-512" />
         </Realm>
         

      3. Eclipse may complain when you try to run your server. You need to tell it to sync your filesystem and workspace so it's aware of external changes. Go to Window > Preferences > General > Workspace and check the Refresh Automatically box. Then hit Apply and Ok

   2. Turn off persistent sessions
      By default, Tomcat will try to save sessions in between server restarts. We don't want this to happen since we cache certain objects in the session that can't be serialize and cause tomcat to spit out useless errors. To turn this off, replace the Context tag in the server.xml file (from the previous step) with the following tag: 

      <Context docBase="starexec" path="/starexec" reloadable="true" source="org.eclipse.jst.jee.server:starexec">
          <!-- Disable persistant sessions -->
          <Manager className="org.apache.catalina.session.StandardManager" pathname=""/>
      </Context>
      

5. Configure StarExec
   Everything should now be set up correctly except for StarExec configurations that are specific to your machine. By default StarExec loads a configuration file when it is started on a server. It is located along with all of the other config files in the project directory under starexec\src\com\starexec\config\starexec-config.xml The file contains configurations for multiple users (e.g. production, tyler local dev, tyler cluster dev, etc.) to allow easy switching between configurations. You need to copy and existing <configuration> node and paste it below another. Then change the name attribute on your configuration node to something meaningful such as "bob dev local". Then you'll need to change the appropriate fields. The only ones that need to be changed are the MySql properties (change them to match your local setup of MySql) and anything that is a PATH property. Change all paths to existing paths on your system (some such as Benchmark and Solver paths need to be created by you manually). If you need help setting this up, consult a lead developer. Finally at the very top in the starexec-configuration node, change the default attribute to whatever your named your configuration node.
6. Set up SGE emulation (optional)
   Follow the directions here to set up grid engine emulation

Cluster

Pending by CJ

• Install Tomcat
• Configure Tomcat

• Configure MySql
  Have another developer or yourself set up your mysql development accounts
  Login under root

  CREATE DATABASE dev_xy_starexec;
  GRANT ALL PRIVELEGES ON dev_xy_starexec.* TO 'dev_star_root'@'localhost';
  GRANT SELECT, INSERT, UPDATE, DELETE ON dev_xy_starexec.* TO 'dev_star_app'@'localhost';

• Configure StarExec
• Setup Scripts
• Run Tomcat/StarExec