Installation:3.0-beta

Downloading Binaries
Binaries can be downloaded from our Sourceforge project page here.

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

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.

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.

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 The first part of the message printed to the screen should contain the version of the Subversion command-line client that you installed.

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:

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:

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

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

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

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  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]

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:

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

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

You should now see ping-iostore-berkeleydb-core-3.0-beta-bin.tar.gz in the target/ directory.

$ tar -xzvf ping-iostore-berkeleydb-core-3.0-beta-bin.tar.gz
 * Copy the IO Store package to your server and extract their contents.

$ mv ping-iostore-berkeleydb-core-3.0-beta-bin /usr/local/indivo-store $ cd /usr/local/indivo-store/bin
 * Move the IO Store folder to a suitable location and navigate to its  directory.

$ chmod a+x *.sh
 * Make sure all the scripts are executable.


 * 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  .  In our last release, the script is incorrect.  Change   to.

$ ./startStore.sh OSStoreServer /usr/local/indivo-store/ \ OSStoreServerAudit /usr/local/indivo-store/ &
 * Start the IO Store in the background.

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.

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.

$ tar -xzvf ping-utils-3.0-beta-bin.tar.gz
 * Copy the Utils package to your Store's server and extract its contents.

$ cd ping-utils-3.0-beta-bin/bin
 * Navigate to the Utils  directory.

$ chmod a+x *.sh
 * Make sure all the scripts are executable.

$ ./createKeystore.sh keystoreLocation keystorePasswd keyAlias keyPasswd hmacKeyAlias hmacKeyPasswd
 * Create a keystore for your IO Store.


 * 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

$ keytool -list -keystore keystoreLocation -storetype jceks
 * Verify that there are two keys in your new keystore.

$ ./createAccount.sh recordStoreClassname storeLocation auditStoreLocation creatorID creatorName \ creatorRole newAccountID newAccountPassword newAccountRole keystoreLocation \ keystorePasswd keyAlias keyPasswd cipherAlgorithm hmacAlgorithm hmacKeyAlias hmacKeyPasswd
 * 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).


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

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.

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:

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.

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.

Installation Instructions
$ mvn clean install
 * Build the entire Indivo project.

$ tar -xzvf ping-ui-php-3.0-beta-deploy.tar.gz $ mv ping-ui-php-3.0-beta-deploy/** /var/www/html/
 * Copy the UI archive (found in ) 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-client-php-3.0-beta.tar.gz $ mv ping-client-php-3.0-beta /usr/local/indivo-php-client
 * Copy the PHP Client archive (found in ) to your webserver. Extract its contents somewhere outside your webserver's directory structure.


 * 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 &#39;&#39;,   `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 &#39;&#39;,   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 &#39;&#39;,   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 &#39;&#39;,   `datein` datetime NOT NULL default '0000-00-00 00:00:00',   `dateout` datetime default NULL,   `sessionid` varchar(50) NOT NULL default &#39;&#39;,   `ipaddress` varchar(50) default &#39;&#39; );

Configuration

 * If necessary, configure your webserver to point to the directory where you extracted the UI code.


 * Find  in the extracted PHP Client directory and open it in a text editor.  Confirm that filenames in the   fields match the files in the   subdirectory.  Fill in the blanks, namely:
 * the  field
 * the  field
 * the  fields


 * Find  in the UI's   subdirectory. Rename it to   and open it in a text editor.  Fill in the blanks.  For a detailed description of "the blanks," read Config.xml.php Explained.


 * Open  in the UI's   subdirectory in a text editor.  Change line 12 to reflect your preferred Indivo ID domain.

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:



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