Installation:3.1 Server and Store

From OpenIndivo Documentation Wiki

Jump to: navigation, search

Contents

[edit]

Getting Indivo

[edit]

Downloading Binaries

Binaries can be downloaded from our Sourceforge project page.

[edit]

Building from Source

To build Indivo from source, you'll need to install Java, Maven, and Subversion. Instructions/specifications for each follow.

[edit]

Install Java

Indivo requires Java 5. You can download the Java 5 SDK from Sun Microsystems. (The Maven build process will fail when using Java 6)

Installation instructions are also available on the Java website.

For Microsoft Windows users, you can check out our Installing And Configuring Java - Windows page.

[edit]

Install Maven

The Apache Maven build environment is a scriptable tool that is used in the building of Indivo. Indivo requires Maven version 2.0.4 or greater. Download the latest copy of Maven.

Installation instructions are provided on the Maven website's download page.

For Microsoft Windows users, you can check out our Installing and Configuring Maven - Windows page.

[edit]

Install Subversion

Subversion is a source code repository used to manage the software assets of the Indivo project. To retrieve the source code from the repository, download the latest copy of the Subversion client.

For the Windows platform, follow the link for the prepackaged binaries and download the file named svn-1.3.2-setup.exe or later.

Once installed, open a command prompt and type 

 svn help

The first part of the message printed to the screen should contain the version of the Subversion command-line client that you installed.

[edit]

Download the code

All source code is available for public download and browsing. You can browse the source code on the web through our Subversion repository or use our Fisheye viewer. There are three subdirectories: branches, tags, trunk.

  • branches contains all development branches (both active and inactive) that
  • tags contains all tags for Indivo milestones (releases, etc)
  • trunk contains the main development trunk

You can also use Subversion to download the code onto your local machine. From the command-line, execute the command: 

 svn co https://scm.chip.org/svn/repos/ping/trunk indivo

to check out the trunk of the code base and place it in the indivo directory.

Similarly, to check out a specific tag like the most recent release execute the command: 

 svn co https://scm.chip.org/svn/repos/ping/tags/indivo-3.1


During checkout, you may see a prompt regarding our repositories SSL certificate. The prompt would read: 

 Error validating server certificate for 'https://scm.chip.org:443':
 - The certificate is not issued by a trusted authority. Use the fingerprint to validate the certificate manually!
 Certificate information:
 - Hostname: scm.chip.org
 - Valid: from Apr 26 20:45:20 2006 GMT until Apr 26 20:45:20 2007 GMT
 - Issuer: Security, CHIP, Boston, Massachusetts, US
 - Fingerprint: 89:14:40:88:c4:f1:c1:e5:50:c0:dd:16:ab:f3:77:0c:f1:92:b7:c8
 (R)eject, accept (t)emporarily or accept (p)ermanently?

Choose 't' or 'p' to continue with the check out.

[edit]

Build the Code

In the base directory of your Indivo checkout, run Maven's install command: 

 $ mvn install

Maven will download all the necessary third-party libraries, compile all the code, and package all the binaries referenced below, except for the UI distributable.

At the end of the mvn install execution, you should see something like the following in your console: 

[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] ------------------------------------------------------------------------
[INFO] Indivo ................................................ SUCCESS [8.418s]
[INFO] Indivo Model .......................................... SUCCESS [0.267s]
[INFO] Indivo Model - Core ................................... SUCCESS [9.877s]
[INFO] Indivo Model - PHR .................................... SUCCESS [6.669s]
[INFO] Indivo Protocol ....................................... SUCCESS [2.316s]
[INFO] Indivo Core ........................................... SUCCESS [8.031s]
[INFO] Indivo Client ......................................... SUCCESS [0.074s]
[INFO] Indivo Client - Java Implementation ................... SUCCESS [1.147s]
[INFO] Indivo Subscription ................................... SUCCESS [0.043s]
[INFO] Indivo Subscription - Model ........................... SUCCESS [0.890s]
[INFO] Indivo Security ....................................... SUCCESS [0.044s]
[INFO] Indivo Security - Model ............................... SUCCESS [0.842s]
[INFO] Indivo Survey ......................................... SUCCESS [0.097s]
[INFO] Indivo Survey Model ................................... SUCCESS [3.219s]
[INFO] Indivo Survey Core .................................... SUCCESS [1.582s]
[INFO] Indivo Security - Core ................................ SUCCESS [0.992s]
[INFO] Indivo Model - Codes .................................. SUCCESS [0.366s]
[INFO] Indivo Client - PHP Implementation .................... SUCCESS [4.337s]
[INFO] Indivo Gene ........................................... SUCCESS [0.057s]
[INFO] Indivo Gene - Model ................................... SUCCESS [2.297s]
[INFO] Indivo Gene - Core .................................... SUCCESS [0.974s]
[INFO] Indivo IO Store ....................................... SUCCESS [0.215s]
[INFO] Indivo IO Store - Berkeley DB ......................... SUCCESS [0.044s]
[INFO] Indivo IO Store - Berkeley DB Model ................... SUCCESS [0.997s]
[INFO] Indivo IO Store - Berkeley DB Core .................... SUCCESS [1.853s]
[INFO] Indivo IO Store - File ................................ SUCCESS [0.423s]
[INFO] Indivo Indexed Record Store ........................... SUCCESS [0.034s]
[INFO] Indivo Indexed Record Store - Model ................... SUCCESS [1.417s]
[INFO] Indivo Indexed Record Store - Core .................... SUCCESS [20.370s]
[INFO] Indivo Utilities ...................................... SUCCESS [0.648s]
[INFO] Indivo M2 Plugins ..................................... SUCCESS [2.372s]
[INFO] Indivo Relational ..................................... SUCCESS [2.424s]
[INFO] Indivo Server ......................................... SUCCESS [0.048s]
[INFO] Indivo Server - Responder ............................. SUCCESS [0.032s]
[INFO] Indivo Server - Responder Config ...................... SUCCESS [1.853s]
[INFO] Indivo Server - Responder Core ........................ SUCCESS [1.517s]
[INFO] Indivo Server - Servlet ............................... SUCCESS [1.457s]
[INFO] Indivo Server - Servlet Demo .......................... SUCCESS [2.611s]
[INFO] Indivo Subscription - Core ............................ SUCCESS [0.677s]
[INFO] Indivo User Interfaces ................................ SUCCESS [0.045s]
[INFO] Indivo User Interfaces - PHP .......................... SUCCESS [2.336s]
[INFO] Indivo Integration Tests .............................. SUCCESS [4:32.842s]
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------

All packages can be found in the various target directories created by Maven.

[edit]

Store Installation

  • Assemble the IO Store package. 
$ cd iostore/berkeleydb/core/
$ mvn assembly:assembly

You should now see indivo-iostore-berkeleydb-core-3.1-bin.tar.gz in the target/ directory.

  • Copy the IO Store package to your server and extract their contents. 
$ tar -xzvf indivo-iostore-berkeleydb-core-3.1-bin.tar.gz
  • Move the IO Store folder to a suitable location and navigate to its bin directory. 
$ mv indivo-iostore-berkeleydb-core-3.1-bin /usr/local/indivo-store
$ cd /usr/local/indivo-store/bin
  • Make sure all the scripts are executable. 
$ chmod a+x *.sh
  • Start the IO Store in the background. 
$ ./startStore.sh OSStoreServer /usr/local/indivo-store/ \
  OSStoreServerAudit /usr/local/indivo-store/ &

The 3.1 release also includes a Windows batch file named startStore.bat and it is equivalent to startStore.sh.

If starting the store in the foreground, you may see log4j warning messages. This simply indicates that you have not yet configured log4j, which is entirely at your discretion.

[edit]

Keystore & Administrator Creation

  • Assemble the Utils package. 
$ cd utils
$ mvn assembly:assembly

You should now see indivo-utils-3.1-bin.tar.gz in the target/ directory.

Creating a keystore is only necessary if you wish to encrypt the data in your Indivo store. While this is highly recommended for production, you may want to skip this step during your initial development/evaluation install.

  • Copy the Utils package to your Server (the machine where you will be deploying the servlet, see below Server Installation) and extract its contents. 
$ tar -xzvf indivo-utils-3.1-bin.tar.gz
  • Navigate to the Utils bin directory. 
$ cd indivo-utils-3.1-bin/bin
  • Make sure all the scripts are executable. 
$ chmod a+x *.sh
  • Create a keystore for your IO Store. 
$ ./createKeystore.sh keystoreLocation keystorePasswd keyAlias keyPasswd hmacKeyAlias hmacKeyPasswd
keystoreLocation 
Physical location where your new keystore will be created, e.g. ../keystore.jks
keystorePasswd 
Password for your keystore
keyAlias 
Alias of the encryption key
keyPasswd 
Password for the encryption key
hmacKeyAlias 
Alias of the HMAC key
hmacKeyPasswd 
Password for the HMAC key
  • Verify that there are two keys in your new keystore. 
$ keytool -list -keystore keystoreLocation -storetype jceks
  • With your IO Store running, create an administrator account. If you chose not to encrypt the data in your Indivo store, you can omit the keystore arguments (all arguments starting with keystoreLocation). 
$ ./createAccount.sh recordStoreClassname storeLocation auditStoreLocation creatorID creatorName \
  creatorRole newAccountID newAccountPassword newAccountRole keystoreLocation \
  keystorePasswd keyAlias keyPasswd cipherAlgorithm hmacAlgorithm hmacKeyAlias hmacKeyPasswd
recordStoreClassname 
The class which defines how the record will be written to the IO Store, typically org.indivo.recordstore.indexedrs.IndexedRecordStore
storeLocation 
The URL to your IO Store, e.g. //localhost/OSStoreServer
auditStoreLocation 
The URL to your Audit Store, e.g. //localhost/OSStoreServerAudit
creatorID 
Indivo ID of the user creating this account, in e-mail address format. This account need not exist. When self-creating your first administrator, for example, feel free to use something artificial like creator@indivohealth.org.
creatorName 
Full name of the user creating this account. When self-creating, this value can be anything you like.
creatorRole 
Role of the user creating this account. When self-creating, this value can be anything you like.
newAccountID 
Indivo ID of the user to be created, in e-mail address format.
newAccountPassword 
New password for the user to be created
newAccountRole 
Role of the user to be created, e.g. administrator, patient, provider, agent
keystoreLocation 
Physical location of your Java keystore (created above)
keystorePasswd 
Password for your keystore
keyAlias 
Alias of the encryption key
keyPasswd 
Password for the encryption key
cipherAlgorithm 
e.g. AES/CBC/PKCS5Padding
hmacAlgorithm 
e.g. HmacSHA1
hmacKeyAlias 
Alias of the HMAC key
hmacKeyPasswd 
Password for the HMAC key
  • If you don't see any errors, you now have a store with an (encrypted) administrator account.
[edit]

Server Installation

[edit]

General instructions

  1. Download the war from Sourceforge.
  2. Deploy the war by following the instructions that your application server provides for war deployment
  3. Start your application server
  4. Verify that the server is deployed by directing a browser to the URL that you deployed your war to. It should look like http://localhost:8080/indivo-server-servlet-demo/IndivoServlet . You should see a message in your browser that reads "I don't respond to GET!" This is the appropriate response.

Windows users, check out our instructions for deploying the Indivo server on Tomcat.

[edit]

Advanced Configuration

If you created an encrypted account in your store, you will need to configure the Action Responders to utilize encryption.

  1. Edit the WEB-INF/classes/responders.xml file in your deployed war
  2. In each responder element, you must edit the StoreConfig and the AuditerConfig by adding a StoreExtensionConfig element. This should be the last element in each *Config. An example of a StoreExtensionConfig for encryption is below: 

   <StoreExtensionConfig xsi:type="conf:SecureStoreExtensionConfigType">
     <ClassName>org.indivo.iostore.extension.SecureStoreExtension</ClassName>
     <KeystoreLocation>keytoreLocation</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>

You'll also need to define the "conf" namespace. You can do this by adding 

xmlns:conf="http://indivo.org/xml/config"

once in your responderConfig element's start tag or in every StoreExtensionConfig elements' start tag.

Retrieved from "http://wiki.indivohealth.org/index.php/Installation:3.1_Server_and_Store"
Personal tools