Installation:3.0-beta

From OpenIndivo Documentation Wiki

Jump to: navigation, search

Contents

[edit]

Getting Indivo

[edit]

Downloading Binaries

Binaries can be downloaded from our Sourceforge project page here.

[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 here. (The Maven build process will fail when using Java 6 -- you have been warned.)

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 here.

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 here.

For the Windows platform, follow the link for the prepackaged binaries here 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 here. 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 beta execute the command: 

 svn co https://scm.chip.org/svn/repos/ping/tags/ping-3.0-beta


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, output from mvn install should look like this: 

[INFO]
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] ------------------------------------------------------------------------
[INFO] PING .................................................. SUCCESS [1:40.681s]
[INFO] PING Model ............................................ SUCCESS [5.765s]
[INFO] PING Model - Core ..................................... SUCCESS [1:43.934s]
[INFO] PING Model - PHR ...................................... SUCCESS [10.030s]

[INFO] PING Protocol ......................................... SUCCESS [1.516s]
[INFO] PING Core ............................................. SUCCESS [15.781s]

[INFO] PING Client ........................................... SUCCESS [0.015s]
[INFO] PING Client - Java Implementation ..................... SUCCESS [0.969s]
[INFO] PING Survey ........................................... SUCCESS [0.016s]
[INFO] PING Survey Model ..................................... SUCCESS [1.359s]
[INFO] PING Survey Core ...................................... SUCCESS [10.046s]

[INFO] PING Security ......................................... SUCCESS [0.000s]
[INFO] PING Security - Model ................................. SUCCESS [0.578s]
[INFO] PING Security - Core .................................. SUCCESS [1.047s]
[INFO] PING Subscription ..................................... SUCCESS [0.000s]
[INFO] PING Subscription - Model ............................. SUCCESS [0.750s]
[INFO] PING Subscription - Core .............................. SUCCESS [8.656s]
[INFO] PING Model - Codes .................................... SUCCESS [0.328s]
[INFO] PING Client - PHP Implementation ...................... SUCCESS [27.749s]

[INFO] PING Gene ............................................. SUCCESS [0.015s]
[INFO] PING Gene - Model ..................................... SUCCESS [1.313s]
[INFO] PING Gene - Core ...................................... SUCCESS [0.812s]
[INFO] PING IO Store ......................................... SUCCESS [0.000s]
[INFO] PING IO Store - Berkeley DB ........................... SUCCESS [0.016s]
[INFO] PING IO Store - Berkeley DB Model ..................... SUCCESS [0.641s]
[INFO] PING IO Store - Berkeley DB Core ...................... SUCCESS [2.625s]
[INFO] PING IO Store - File .................................. SUCCESS [0.515s]
[INFO] PING Indexed Record Store ............................. SUCCESS [0.016s]
[INFO] PING Indexed Record Store - Model ..................... SUCCESS [0.922s]
[INFO] PING Indexed Record Store - Core ...................... SUCCESS [3.312s]
[INFO] PING Utilities ........................................ SUCCESS [0.562s]
[INFO] PING M2 Plugins ....................................... SUCCESS [33.093s]

[INFO] PING Server ........................................... SUCCESS [0.016s]
[INFO] PING Server - Responder ............................... SUCCESS [0.000s]
[INFO] PING Server - Responder Config ........................ SUCCESS [0.921s]
[INFO] PING Server - Responder Core .......................... SUCCESS [1.172s]
[INFO] PING Server - Servlet ................................. SUCCESS [2.438s]
[INFO] PING Server - Servlet Demo ............................ SUCCESS [5.234s]
[INFO] PING User Interfaces .................................. SUCCESS [0.015s]
[INFO] PING User Interfaces - PHP ............................ SUCCESS [1.500s]
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 5 minutes 45 seconds
[INFO] Finished at: Tue Oct 17 12:05:17 EDT 2006
[INFO] Final Memory: 16M/34M
[INFO] ------------------------------------------------------------------------


[edit]
Versions 3.0-beta and Earlier

In 3.0-SNAPSHOT and beyond, this step is not necessary.

To create the UI package, navigate to the ui/php directory, and run the assembly command: 

 $ mvn assembly:assembly

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 ping-iostore-berkeleydb-core-3.0-beta-bin.tar.gz in the target/ directory.

  • Copy the IO Store package to your server and extract their contents. 
$ tar -xzvf ping-iostore-berkeleydb-core-3.0-beta-bin.tar.gz
  • Move the IO Store folder to a suitable location and navigate to its bin directory. 
$ mv ping-iostore-berkeleydb-core-3.0-beta-bin /usr/local/indivo-store
$ cd /usr/local/indivo-store/bin
  • Make sure all the scripts are executable. 
$ chmod a+x *.sh
  • Verify that the scripts use the correct version number (sometimes we forget to update them!) You should edit your script such that the PING_VERSION environment variable is assigned to the version of the store that you are running. Our latest release version is 3.0-beta. In our last release, the script is incorrect. Change 3.0-beta-SNAPSHOT to 3.0-beta.
  • Start the IO Store in the background. 
$ ./startStore.sh OSStoreServer /usr/local/indivo-store/ \
  OSStoreServerAudit /usr/local/indivo-store/ &

The 3.0-beta release does not include a Windows batch file equivalent to startStore.sh, but it is easily implementable using startStore.sh as a guide. (It will be included in the full 3.0 release.)

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

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 Store's server and extract its contents. 
$ tar -xzvf ping-utils-3.0-beta-bin.tar.gz
  • Navigate to the Utils bin directory. 
$ cd ping-utils-3.0-beta-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 defiens how the record will be written to the IO Store, typically org.chip.ping.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/PingServlet . 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 PingStoreConfig and the AuditStoreConfig by adding a StoreExtensionConfig element. This should be the last element in each xStoreConfig. An example of a StoreExtensionConfig for encryption is below: 

   <StoreExtensionConfig xsi:type="pingc:SecureStoreExtensionConfigType">
     <ClassName>org.chip.ping.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 "pingc" namespace. You can do this by adding 

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

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

[edit]

User Interface Installation

[edit]

Requirements

  • Java 1.5+
  • Apache 2.0 webserver (not 2.2!)
  • PHP 5.1.2 AND NO HIGHER (with MySQL, GD, and FreeType support -- these are not enabled by default!)
  • PEAR packages DB, Log, and Config (with all dependencies)
  • PHP-Java Bridge version 3.0.7
  • MySQL database (for logging, accessible by the webserver)

See Setting Up Your UI Server for tips on installing these preliminaries.

NOTE: THE USER INTERFACE WILL NOT WORK IF YOU DO NOT USE THESE EXACT VERSIONS OF THE SOFTWARE WE REQUIRE. IF YOU TRY OTHER VERSIONS, YOU WILL SIMPLY BE WASTING YOUR TIME.

[edit]

Installation Instructions

  • Build the entire Indivo project. 
$ mvn clean install
  • Copy the UI archive (found in ui\php\target) to your webserver. Extract its contents to a web-servable directory. (Alternatively, you may point Apache's DocumentRoot directly to the webapps folder in your Indivo source distribution.) 
$ tar -xzvf ping-ui-php-3.0-beta-deploy.tar.gz
$ mv ping-ui-php-3.0-beta-deploy/** /var/www/html/
  • Copy the PHP Client archive (found in client\php\target) to your webserver. Extract its contents somewhere outside your webserver's directory structure. 
$ tar -xzvf ping-client-php-3.0-beta.tar.gz
$ mv ping-client-php-3.0-beta /usr/local/indivo-php-client
  • Create the logging tables in your database, using the following SQL to create them: 
CREATE TABLE `log` (
  `LogDate` datetime NOT NULL default '0000-00-00 00:00:00',
  `LogTime` float NOT NULL default '0',
  `Class` varchar(100) default NULL,
  `Function` varchar(100) default NULL,
  `Filename` varchar(255) NOT NULL default '',
  `Line` int(10) unsigned NOT NULL default '0',
  `SessionID` varchar(45) default NULL,
  `Message` text NOT NULL,
  `Flag` int(10) unsigned NOT NULL default '0',
  `Priority` int(10) unsigned NOT NULL default '0',
  `id` varchar(13) NOT NULL default '0',
  `Ident` varchar(16) NOT NULL default '',
  PRIMARY KEY  (`id`),
  KEY `Index_Log_SessionID` (`SessionID`),
  KEY `Index_Log_Level` (`LogDate`)
);

CREATE TABLE `priority` (
  `PriorityId` int(11) NOT NULL default '0',
  `Description` varchar(45) NOT NULL default '',
  PRIMARY KEY  (`PriorityId`)
);

INSERT INTO `priority` (`PriorityId`,`Description`) VALUES 
 (0,'Emergency'),
 (1,'Alert'),
 (2,'Critical'),
 (3,'Error'),
 (4,'Warning'),
 (5,'Notice'),
 (6,'Information'),
 (7,'Debug');

CREATE TABLE `logins` (
  `userid` varchar(255) NOT NULL default '',
  `datein` datetime NOT NULL default '0000-00-00 00:00:00',
  `dateout` datetime default NULL,
  `sessionid` varchar(50) NOT NULL default '',
  `ipaddress` varchar(50) default ''
);
[edit]

Configuration

  • If necessary, configure your webserver to point to the directory where you extracted the UI code.
  • Find apiConfig.xml in the extracted PHP Client directory and open it in a text editor. Confirm that filenames in the jar fields match the files in the lib subdirectory. Fill in the blanks, namely:
    • the serverUrl field
    • the libraryPath field
    • the logging fields
  • Find config.xml.php.orig in the UI's config subdirectory. Rename it to config.xml.php and open it in a text editor. Fill in the blanks. For a detailed description of "the blanks," read Config.xml.php Explained.
  • Open validator.js in the UI's resources/js subdirectory in a text editor. Change line 12 to reflect your preferred Indivo ID domain.
[edit]

Testing

Open a browser and visit the URL at which you set up the UI. Give it a whirl.

Note: A record must have a single contact information document in order for login to succeed. The default administrator created in the Keystore & Administrator Creation instructions above does not come with a contact information document, so we've included a setup script which will add such a document to your adminstrator record, accessible via:

http://path.to.ui/config/setup.php?username=XXX&password=XXX

Just use the correct path to your UI site, and provide your administrator's full username (i.e. admin@indivohealth.org) and password as URL variables. (This is also a good way to test the entire Indivo setup ... if it works, you're in great shape.)

Retrieved from "http://wiki.indivohealth.org/index.php/Installation:3.0-beta"
Personal tools