wiki:InstallationGuide

Installation Guide

noreorder)?

Overview

The purpose of this document is to describe the steps for installing MooreRecruiting on a host for use as a test or production server. The terminology used in this document will generally be based on an installation to a Linux environment. That should not limit your ability to install the code in a Windows environment. The following software is required for obtaining the MooreRecruiting source, compiling it, and deploying to your environment:

Install Dependent Software

  1. Setup Web and Mail Server
  2. Install MySQL
  3. Install Java
  4. Install Maven
  5. Install Tomcat
  6. Install Subversion

Obtaining The Source Code

A copy of the MooreRecruiting source code can be obtained by emailing SSEL Admin for a guest account in our SVN respository.

Note: you may see the name "recruiting" used a lot here. It is the informal name for the MooreRecruiting Experiment management system. A password may be required to gain access to the source. The recruiting directory contains an Appfuse 2 project which uses the Maven build system.

Compiling The Source

If you have Java and Maven installed, change directory into recruiting and run the command mvn compile. A lot of time may pass, as Maven downloads project and Appfuse dependent archives. Initially, the compile step will fail. Maven will report:

[INFO] Failed to resolve artifact.

Missing:
----------
1) paygatesoapclient:paygatesoapclient:jar:1.0.1

  Try downloading the file manually from the project website.

  Then, install it using the command: 
      mvn install:install-file -DgroupId=paygatesoapclient -DartifactId=paygatesoapclient \
          -Dversion=1.0.1 -Dpackaging=jar -Dfile=/path/to/file

You'll find the missing artifact here: third_party/paygatesoapclient-1.0.1.jar. Follow the Maven instruction above to install the missing dependency. Then rerun mvn compile. Your application should compile and report:

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 11 seconds

although your system may not complete in 11 seconds!.

Next, if MySQL is installed and running, attempt to connect to your MySQL database and build the recruiting schema using hibernate. MooreRecruiting uses the username "root" and a blank password by default. To change these values to suit your MySQL environment, modify the <jdbc.username> and <jdbc.password> properties in your project's pom.xml (at the bottom). When you are satisfied that you have correct database credentials set up, run mvn hibernate3:hbm2ddl.

If all goes well, your command should complete successfully and the recruiting database has been created. An excellent, Java based database editor can be found here: DBVisualizer so you can examine your recruiting database (named recruiting).

Running The Application

Now, run the command mvn jetty:run-war. This will build the app and deploy the web application to a local project directory in an embedded http://www.mortbay.org Jetty application server. You'll know the application is ready to view if you see Maven report:

[INFO] Started Jetty Server
[INFO] Starting scanner at interval of 3 seconds.

At this point, you should be able to browse to the URL: http://localhost:8080 and see the MooreRecruiting login screen! Try to login as admin/admin and you will be taken to the Administrator home page.

Running In Tomcat

Now that you've been able to build a web application from source and run it inside the embedded Jetty server, let's configure Tomcat and drop a war file in it's web app directory to see how it runs from there. Refer to Tomcat documentation for details on Tomcat setup. Also, once unpacked, a file named RUNNING.txt can be found in the Tomcat root directory which has detailed instructions on running Tomcat in a Linux or Windows environment. Tomcat, once installed, is missing some Axis Web Services libraries used by MooreRecruiting to communicate with the integrated payment gateway, which is used to make PayPal payments. The missing libraries are:

  • axis.jar
  • commons-discovery-0.2.jar
  • jaxrpc.jar
  • saaj.jar
  • wsdl4j-1.5.1.jar

These jars need to be copied into the Tomcat shared/lib directory. The files can be copied from the project web application directory recruiting/target/recruiting-1.0-SNAPSHOT/WEB-INF/lib created when the application was run in place. From the recruiting directory run mvn package. This will create the war file target/recruiting-1.0-SNAPSHOT.war. Copy this jar file into the Tomcat webapp directory as recruiting.jar. You are ready to run the application in Tomcat. There are other methods to deploy to Tomcat within the Maven build system. This manual method doesn't involve modifying the Maven project pom.xml.

Start tomcat and browse to http://localhost:8080/recruiting. You should see the MooreRecruiting login screen served by Tomcat.

Apache and HTTPS

For a number of reasons, you may want to use the Apache or another web server as a proxy server and run it in front of the MooreRecruiting application. And you probably also want to use https and an ssl server certificate to protect communication. Following is a method that can be used to do this for MooreRecruiting running in Tomcat.

Tomcat needs to be configured to return calls to the recruiting application with the correct http scheme and port. Edit the Tomcat root directory conf/server.xml file. Find the location of the Connector definition running on port 8080. Add the attributes proxyPort="443" scheme="https". This will keep Tomcat from switching schemes or ports on return calls from the application. This should be all you need to do to Tomcat!

Configuring Apache, ssl and using it to proxy to Tomcat is another matter, of course. Apache configuration files vary in layout and administration across Linux distributions. In many cases, a web server is used in front of multiple applications, so let's set up a basic Apache name "virtual host". Depending on the Apache installation, this might involve editing an existing apache configuration file, like httpd.conf or apache2.conf, or it might involve creating a new config file in the conf.d directory. At any rate, the new config looks like this:

NameVirtualHost *:80
<VirtualHost *:80>
    ServerAdmin recruiting@myschool.edu
    DocumentRoot /var/www/recruiting
    ServerName recruiting.my_school.com
    ErrorLog logs/recruiting.my_school.com-error_log
    CustomLog logs/recruiting.my_school.com-access_log common
    <Directory /var/www/recruiting>
        Options Indexes FollowSymLinks MultiViews
        AllowOverride None
        Order allow,deny
        allow from all
    </Directory>

    <Proxy *>
        Order deny,allow
        Allow from all
    </Proxy>
    ProxyPreserveHost On
    ProxyPass         /recruiting  http://localhost:8080/recruiting
    ProxyPassReverse  /recruiting  http://localhost:8080/recruiting
</VirtualHost>

The "addr" in NameVirtualHost addr[:port] represents the IP address to which your name-based virtual host names resolve. To receive requests on all interfaces, you can use an argument of *. Once the configuration above is in place, you can restart Apache, leaving browse to http://localhost/recruiting and Apache should pass the request on to the running Tomcat.

To enable ssl and https, add the following config and define a new ssl virtual host definition:

LoadModule ssl_module modules/mod_ssl.so
Listen 443
NameVirtualHost *:443
<VirtualHost *:443>
    ServerAdmin recruiting@myschool.edu
    SSLEngine on
    SSLCertificateFile /etc/httpd/ssl/apache.pem
    DocumentRoot /var/www/recruiting
    ServerName recruiting.my_school.com
    ErrorLog logs/recruiting.my_school.com-ssl_error_log
    CustomLog logs/recruiting.my_school.com-ssl_access_log common
    <Directory /var/www/recruiting>
        Options Indexes FollowSymLinks MultiViews
        AllowOverride None
        Order allow,deny
        allow from all
    </Directory>

    <Proxy *>
        Order deny,allow
        Allow from all
    </Proxy>
    SSLProxyEngine On
    ProxyPreserveHost On
    ProxyPass         /recruiting  http://localhost:8080/recruiting
    ProxyPassReverse  /recruiting  http://localhost:8080/recruiting
</VirtualHost>

There are many other Apache configuration directives that can be employed. These are just a few of them. Note, the configuration about uses a ssl certificate /etc/httpd/ssl/apache.pem. To use ssl, you must obtain a server certificate or create one?.

Mail

Appfuse includes a file: src/main/resources/mail.properties for configuring a mail host and other properties. If you already have an SMTP mail server present locally, you won't have to modify this file, unless your server requires authentication. If your server requires authentication, you will need to:

  • Add values to mail.username and mail.password properties in src/main/resources/mail.properties
  • Edit the spring bean config file src/main/webapp/WEB-INF/applicationContext.xml and locate the "mailSender" bean, where you will need to uncomment a couple of additional authentication properties.

The Appfuse project provides some more information on SMTP servers if you are unsure of what to use.

Set up MySQL

In a command prompt, move to the moorerecruiting folder. Then to enter the MySQL shell, type:

mysql -uroot -p

Enter the password you set up earlier in the MySQL installation process. Create the database by typing:

create database recruiting;  

Create the database user by typing:

grant all privileges on recruiting.* to mr@localhost identified by 'banana';
flush privileges;

Next, load the database schema with:

use recruiting;
source recruiting.sql; 
Last modified 8 years ago Last modified on Oct 8, 2010 12:58:27 PM