Installation guide

From HiWiki

Jump to: navigation, search

PING Discovery: Pilot implementasjon og utforskning av PING -> Installation guide

This guide describes how to install the PING Server 3.0 Alpha-2 Release with encrypted RMI store server. See the old installation guide for information on how to install the server without encryption. If you only are looking for a demo of the version made at NSEP go here.

Contents

[edit]

Download PING source code

Get the source code from the chip.ping.org repositories: 

svn co https://cvs.chip.org/svn/repos/ping/trunk/ ping
If you use windows we recommend installing TortoiseSVN from http://tortoisesvn.tigris.org/. After installation, create a folder for the source code, right click on it and select Checkout. Enter: 
https://cvs.chip.org/svn/repos/ping/trunk/
[edit]

Install Maven 2

Get the distribution archive from http://maven.apache.org/ and follow the installation instructions on this page: http://maven.apache.org/download.html#Installation

JAXB XJC Maven 2 Plug-in is a plug-in that is able to generate java classes from XML schemas. It has to be installed manually:

Download the plug-in from https://jaxb.dev.java.net/jaxb-maven2-plugin/ and expand the .zip contents into your local user-home/.m2/repository directory. If this is the first time you install maven, you probably don't have the .m2/repository folder yet, because these are created the first time you run maven with a java project.

Run: 
mvn
and check that the folders are created (don't worry about any error messages). If they are not, just create them manually. The structure with the plug-in should be like this:

user-home/.m2/repository/<the plug-in with com/ as the top folder>

[edit]

Install the source code

From the root of the ping source (e.g. user-home/ping/) run: 
mvn -Pintegration-test clean install

This will among other things compile and test the source code, package it into jar files, verify the packages and install them into the local repository. If you get errors or build failures, this could be due to plug-ins that are not downloaded properly. Try to run the same command until it works; the plug-ins should be downloaded eventually.

[edit]

Install tomcat

Install tomcat on the server where you want to run your PingServlet.

[edit]

Deploy the PingServlet on tomcat

Copy the ping-server-servlet-demo-3.0-beta-SNAPSHOT.war file from server/servlet-demo/target/ and place it in tomcat/webapps/. After tomcat has been restarted, the war should be unpacked and the necessary files put in a ping-server folder under webapps. You can try to start the PingServlet from your browser, but it does not respond to GET messages (actually it does but you will know what I mean when you try it), and besides, the RMI data store is not up and running yet. Shutdown tomcat.

[edit]

Prepare PingServlet for encryption

Now we are going to configure a store extension in responders.xml in order to get the PingServlet to encrypt data before it is sent to the RMI store server. Edit responders.xml in the deployed PingServlet's WEB-INF/classes folder and add something similar to this: 

<StoreConfig xsi:type="pingc:OSStoreClientConfigType">
                    <ClassName>org.chip.ping.datastore.objectstore.OSStoreClient</ClassName>
                    <StoreLocation>//localhost/OSStoreServer</StoreLocation>
                    <StoreExtensionConfig xsi:type="pingc:SecureStoreExtensionConfigType">
                        <ClassName>org.chip.ping.datastore.extension.SecureStoreExtension</ClassName>
                        <KeystoreLocation>WEBAPPS_DIR/ping-server/WEB-INF/classes/keystore.jks</KeystoreLocation>
                        <KeystorePassword>keystorePasswd</KeystorePassword>
                        <HMACAlgorithm>HmacSHA1</HMACAlgorithm>
                        <HMACKeyAlias>hmacKeyAlias</HMACKeyAlias>
                        <HMACKeyPassword>hmacKeyPasswd</HMACKeyPassword>
                        <StorageCipherAlgorithm>AES/CBC/PKCS5Padding</StorageCipherAlgorithm>
                        <StorageKeyAlias>keyAlias</StorageKeyAlias>
                        <StorageKeyPassword>keyPasswd</StorageKeyPassword>
                    </StoreExtensionConfig>
                </StoreConfig>

It is only the StoreExtensionConfig part that should be pasted into responders.xml; I included a bit more to show where it should be placed. Btw, enter the part for each StoreConfig. You probably have to add the following to the responderConfig section in responders.xml, because pingc is not defined by default: 

xmlns:pingc="http://ping.chip.org/xml/config"

The passwords and aliases should of course be chosen to be something else than this, but to make things easier, we use these example values consistently.

[edit]

Unpack script for RMI store

Navigate to iostore/berkeleydb/core. Run: 
mvn assembly:assembly
This will create a tar.gz file in the iostore/berkeleydb/core/target directory. The tar.gz file contains all the runtime libraries and a start-up shell script for running the RMI store. Copy the tar.gz file to another directory and unzip it. This will create a new directory named ping-iostore-berkeleydb-core-3.0-beta-SNAPSHOT.
[edit]

Unpack scripts for creating keystore and account

Navigate to utils. Run: 
mvn assembly:assembly
This will create a tar.gz file in the utils/target directory. The tar.gz file contains all the runtime libraries and start-up scripts for creating a keystore and creating an account. Copy the tar.gz file to another directory (storeTest) and unzip it. This will create a new directory named ping-utils-3.0-beta-SNAPSHOT
[edit]

Create keystore

Navigate to ping-utils-3.0-beta-SNAPSHOT/bin. Make sure all the scripts have the executable permission (chmod a+x *.sh).Run: 
./createKeystore.sh ../keystore.jks keystorePasswd keyAlias keyPasswd hmacKeyAlias hmacKeyPasswd
This will create a file keystore.jks in your ping-utils-3.0-beta-SNAPSHOT directory. You can verify that there are two keys in the keystore using the java keytool. Run: 
keytool -list -keystore <location of the keystore.jks file> -storetype jceks
[edit]

Start the RMI store

Navigate to ping-iostore-berkeleydb-core-3.0-beta-SNAPSHOT/bin. Make sure all the scripts have the executable permission. Run: 
 ./startStore.sh OSStoreServer <full-path-to>/ping-iostore-berkeleydb-core-3.0-beta-SNAPSHOT/ 
OSStoreServerAudit <full-path-to>/ping-iostore-berkeleydb-core-3.0-beta-SNAPSHOT/
[edit]

Create account

Now you're going to create your initial account. You'll encrypt it BEFORE you send it to the store. Open a new terminal (your other one is running the store) or send the store process into the background. Navigate back to ping-utils-3.0-beta-SNAPSHOT/bin. Run: 
 ./createAccount.sh org.chip.ping.recordstore.IndexedRecordStore //localhost/OSStoreServer 
//localhost/OSStoreServerAudit creator@ping.chip.org creator administrator admin@ping.chip.org admin 
administrator ../keystore.jks keystorePasswd keyAlias keyPasswd AES/CBC/PKCS5Padding HmacSHA1 hmacKeyAlias hmacKeyPasswd
[edit]

Start/Restart tomcat

Start/Restart tomcat. The PingServlet should now have contact with the RMI data store. To test the system you can write your own methods (using doPOST) for e.g. based on the integration test classes. Later, when you want to start your RMI store again, just follow the procedure as described earlier (Start the RMI store).

[edit]

PING and Netbeans

After some experimentation we found that the only IDE that supported maven 2 and Ping in a satisfactory way, was Netbeans. An installation guide can be found here.

Retrieved from "http://hiwiki.idi.ntnu.no/hiwiki/index.php/Installation_guide"