Developing and Deploying FP-Deployments

From FilteredPush
Jump to: navigation, search

Oracle JDK

Download the latest version of the Java 7 JDK from the following site: http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html.

You may also download from the command line by using the wget command like so (behaves as though the user has clicked the "Accept License Agreement" option on the Oracle download site):

wget --no-check-certificate --no-cookies --header "Cookie: oraclelicense=accept-securebackup-cookie" http://download.oracle.com/otn-pub/java/jdk/7u60-b19/jdk-7u60-linux-x64.tar.gz

Unpack the downloaded archive and move the jdk1.7.0_51 directory to /usr/lib/jvm:

tar -xzvf jdk-7u60-linux-x64.tar.gz 
sudo mv jdk1.7.0_60 /usr/lib/jvm/

Use update-alternatives to set which version of Java to use (Note that if you have OpenJDK installed on Debian or Ubuntu the priority for java is 1061 by default. The value of 2000 specified below will override this):

sudo update-alternatives --install "/usr/bin/java" "java" "/usr/lib/jvm/jdk1.7.0_60/bin/java" 2000
sudo update-alternatives --install "/usr/bin/javac" "javac" "/usr/lib/jvm/jdk1.7.0_60/bin/javac" 2000
sudo update-alternatives --install "/usr/bin/javaws" "javaws" "/usr/lib/jvm/jdk1.7.0_60/bin/javaws" 2000

Use check the java version to confirm that the system is now using the Oracle JDK:

java -version
java version "1.7.0_60"
Java(TM) SE Runtime Environment (build 1.7.0_60-b19)
Java HotSpot(TM) 64-Bit Server VM (build 24.60-b09, mixed mode)

Edit /etc/environment to set the global JAVA_HOME variable to /usr/lib/jvm/jdk1.7.0_51:

sudo su
echo "JAVA_HOME=/usr/lib/jvm/jdk1.7.0_60" >> /etc/environment

Install Dev Prerequisites

First install Maven and Subversion:

sudo apt-get install maven subversion

Download the latest version of the Eclipse IDE for Java EE Developers (Kepler at the time of writing) from: https://www.eclipse.org/downloads/

Unpack the archive and move the eclipse directory to /opt:

tar -xzvf eclipse-jee-kepler-SR2-linux-gtk-x86_64.tar.gz 
sudo mv eclipse /opt/

Create a symlink in /usr/bin:

sudo ln -s /opt/eclipse/eclipse /usr/bin/eclipse

NOTE: The /opt/eclipse directories permissions should allow the user write permissions on the directories (such as configuration and plugins). You may have to change ownership if the directory is owned by root after unpacking/moving as this will interfere with plugin installation within Eclipse.

Install the Subclipse plugin

The subclipse plugin for Eclipse includes a version of SVN of its own. In order to ensure that you have the option to use either svn on the command line or subclipse within Eclipse regardless of how the project was checked out it is important to make sure that the version of Subclipse you install is compatible with the version of Subversion you have installed. You can check your Subversion version via svn --version in the shell (at the time of writting this was 1.6.17 on Debian). The update site to use will depend on this version, see the download link at http://subclipse.tigris.org/ for more info.

The update site for Subversion 1.6.x is http://subclipse.tigris.org/update_1.6.x/ Select the Hellp > Install New Software option from the menu and click the "Add" button to add the install site. Give it a name and enter the update site url that corresponds to your Subversion then click "OK". From the list of items to instal select "Subclipse" and the "Core SVNKit Library" then click "Next" and install the plugin. Once the plugin finishes installing you will be prompted to restart Eclipse.

If after restarting you receive an error of the form "Failed to load JavaHL Library." you will have to switch to the SVNKit implementation. Go to Window > Preferences in the main menu and select Team > SVN on the left in the Preferences dialog. Near the bottom of the SVN settings you should see a dropdown box below the "SVN Interface" label for the Client. Pick the SVNKit option from this list and click ok. Now if you restart Eclipse the error should be resolved.

Subclipse SCM Connector

Open the preferences dialog in Eclipse via Window > Preferences and select Maven > Discovery from the list on the left. Click the "Open Catalog" button and scroll to the bottom of the list, find the m2e-subclipse entry and select it. Click finish to install. Once the installer finishes it will prompt you to restart Eclipse.

Checkout FP-Deployments

Select the File > New > Other menu option and in the "New" wizard, find and select Maven > Checkout Maven Projects from SCM before clicking "Next".

Select svn as the SCM url and use the following url in the text entry field beside it: https://svn.code.sf.net/p/filteredpush/svn/trunk/FP-Deployments. Click next, keep the defaults on the next page unless you wish to change them and click Finish to check out the project.

If you are doing a command-line deployment you may also use the following:

svn co http://svn.code.sf.net/p/filteredpush/svn/trunk/FP-Deployments

Configuration for FP-Core

Before building, if you will be running tests (you may skip tests via maven option -Dmaven.test.skip=true), you will need to create a test.properties file from the template in FP-Core/src/test/resources/test.properties.template and configure it for your workspace.

If you would like to run tests using different implementations of the triple store and document store (as opposed to the default embedded instances) see the properties listed below in FP-Core/pom.xml:

   <properties>
       <test.knowledge.docstore.impl>EmbeddedOrientDB</test.knowledge.docstore.impl>
       <test.knowledge.triplestore.impl>EmbeddedTDB</test.knowledge.triplestore.impl>
       <test.knowledge.objstore.impl>MongoDB</test.knowledge.objstore.impl>
   </properties>

Each of these is the Java class name that corresponds to an implementation of the relevant interface (see packages under org.filteredpush.knowledge in FP-Core for different implementations of TripleStore and DocumentStore.

Configuration for FP-Service and FP-Client on the same machine

Typically, for a development installation of a full FP, the FP-Service and FP-Client will be on the same machine. For production environments this may not be the case. For a development installation, embedded java triple stores and document stores will be used. MongoDB is not a java project, so you will need to install it separately:

sudo apt-get install mongodb

First create the directory that you plan on using as the Filteredpush configuration home (e.g. /home/<user>/fp. Within this directory create a directory for the triple store (annotations) and a directory for the document store (docstore). These must be readable and writable by the user executing the FP-Service. For a development environment under eclipse, the FP-Service will also run as the eclipse user.

mkdir -p fp/annotations
mkdir -p fp/docstore  

You will next need to generate a key and a keystore for client authentication with the access point. Use the following command. We will use the same password for the keystore and for this alias. Below, "<keystore.location>" is a file that will contain Public Key Infrastructure (PKI) private keys. When building a deployment that will run under eclipse, this file must be accessible to the eclipse user but should be inaccessible to every other user. Place this file in the fp config home directory you created in the previous step.

keytool -genkey -alias test-alias -keyalg RSA -keystore keystore.jks -keysize 2048
Enter keystore password:  test-password
Re-enter new password: test-password
...
(Informational questions: It will help with administration if you can answer them accurately.)
...
Enter key password for <client-alias>
(RETURN if same as keystore password):

At this point, you can find a copy of the latest domain configuration for apple pie at FP-Service/src/main/resources/ApplePieConfig.xml. Make a copy of that and place in in the directory you will use for filteredpush config specified earlier (e.g. /home/<user>/fp).

Your fp home directory should look like the following

\fp
----\annotations
----\docstore
----ApplePieConfig.xml
----keystore.jks

Global configuration

In the FP-Deployments (parent) project create a copy of the file located at src/main/filters/filter.properties.template and name it filter.properties. Refer to the summary below when making changes to the default values in this file:

  • domain.config.dir - set this to the location of your domain configuration xml. Use the DomainConfiguration.xml file provided in FP-Service/src/main/resources for ApplePie deployments.
  • keystore.location - the location of the keystore file created previously
  • keystore.password - the keystore password
  • keystore.alias - the alias for the client key in the keystore (a deployment of FP-Client configured for a specific client will use this when signing messages)
  • keystore.cert.password - the certificate alias set when keytool was invoked
  • triplestore.dir - the location that should be used for the embedded triplestore data
  • docstore.dir - the location that should be used for the embedded documentstore data
  • accesspoint.host - the hostname of the machine that access point will be deployed to
  • accesspoint.port - the port that the access point will use

When this is done, do the same thing for /FP-Deployments/src/main/filters/filter.properties.template. However, since you are deploying on a single machine, you should make all the values be the same as for the filter.properties you just made above.

Once you have created these files you can right click the FP-Deployments project under the Project Explorer in Eclipse, select Maven > Update Project. In the update dialog click "Select All" followed by OK to update the projects that depend on the filter.properties file. This will remove any warnings about this file missing in your workspace.

Maven install and deploy

Temporary hack

A repository specified by a transitive dependency has been down for some time now: Chuck has contacted Aduna (the folks with the down repo) and FC (the folks referencing the down repo): FC has said they will look into it. In the meanwhile, we don't actually need that repo: the packages are available elsewhere, but the maven build stalls out. The work-around is to add a ~/.m2/settings.xml:

 <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.0
                     http://maven.apache.org/xsd/settings-1.0.0.xsd">
   <localRepository/>
   <interactiveMode/>
   <usePluginRegistry/>
   <offline/>
   <pluginGroups/>
   <servers/>
   <mirrors>
     <mirror>
       <id>useInstead</id>
       <name>Maven central</name>
       <url>http://repo.maven.apache.org/maven2/</url>
       <mirrorOf>aduna</mirrorOf>
     </mirror>
   </mirrors>
   <proxies/>
   <profiles/>
   <activeProfiles/>
 </settings>

This is essentially a no-op: Obviously central is already being used, so specifying it as a mirror just means that we don't try and end up getting stuck with aduna.

Normal install

To build the deployable artifacts first run mvn install on FP-Deployments by right clicking the FP-Deployments project in the Project Explorer and selecting the Run As > Maven Install menu option. Then build the assemblies via mvn install assembly:single for FP-Service and FP-Client. To do this within Eclipse right click the FP-Service project in the Project Explorer and select the Run As > Maven Build... menu option to create a new build configuration. In the dialog find the text field labeled "Goals" and enter install assembly:single and click Run. Once you have done this for FP-Service do the same for FP-Client.

Extract the contents of FP-Service/target/FP-Service.zip to the directory you would like to install the access point to. Start the access point server from the command line via the following (the first argument is the port):

cd FP-Service/classes
java -cp .:../lib/* org.filteredpush.node.AccessPoint 8081

Next extract the contents of FP-Client/target/FP-Client.zip to the ClientHelper install directory and start the client helper via the following:

java -jar FP-Client-1.0-SNAPSHOT.jar 8080

ClientConnectorTest

To confirm that the network is working run the integration test found in /src/test/java/org/filteredpush/client/ClientConnectorTest.java

Symbiota

Symbiota requires apache2, php and mysql. Install the prerequisites with the following:

sudo apt-get install apache2 php5 libapache2-mod-php5 php5-mysql mysql-server mysql-client

Create the symbiota database and the read/write user(s) in mysql:

mysql> create database symbscan;
mysql> grant all privilleges on symbscan.* to 'symbscan'@'localhost' identified by 'password';

Obtain a copy of the latest dump of SCAN data and import it into the new database.

mysql -u symbscan -p -D symbscan < symbscan_2014-02-21.sql 

Obtain the SCAN templates for the pages and copy them to the root of your symbiota checkout (there is one for each of the template pages in the checkout, i.e. header_template.php, index_tempate.php, etc).

If you wish to host the images for the test instance get these from /imglib/scan and host them in you apache web root (/var/www/imglib/scan for example)

In symbiota/config/ copy the dbconnection_template.php to dbconnection.php and symbini_template.php to symbini.php. Edit dbconnection.php and set the database, username and password for the symbiota database in mysql. Edit the symbini.php file and set the following variables:

  • $clientRoot - Should be the url path for symbiota (relative). For example giving this variable a value of '/symbscan' will configure symbiota to use http://localhost/symbscan as the url.
  • $serverRoot - The full path on the filesystem to symbiota (/var/www/symbscan for example)
  • $imageRootUrl = this should be the URL to the imagelib for scan (i.e. imglib/scan)
  • $imageRootPath = Set this to the path on the filesystem to the images in web root (i.e. /var/www/imglib/scan);

In the symbiota/css directory move and rename jquery-ui_template.css jquery-ui.css. Copy the main.css and speciesprofile.css files from SCAN to the symbiota/css directory in the checkout.

Lastly copy the SCAN collicons to /symbiota/images/collicons in your checkout and then you should be able to deploy symbiota to apache.