Installation:3.0 User Interface

From OpenIndivo Documentation Wiki

Contents 1 Requirements 1.1 Java 1.2 J2EE Application Server 1.3 PHP-Java Bridge 1.4 Webserver 1.5 PHP 1.6 MySQL 2 Installation Instructions 3 Configuration 3.1 Apache 3.2 PHP Client API 3.3 User Interface 4 Testing 5 Administrator Configuration

Requirements

Your UI server must have the following software installed.

NOTE: The user interface has only been tested with the following settings and versions. If you wish to do otherwise, we may not be able to provide support.

Java

• Version 1.5

J2EE Application Server

Optional, to run the PHP Java Bridge in a production setting. (In a development setting, a standalone version of the Bridge may be started from the command line. See below.)

PHP-Java Bridge

• Version 4.1.2

Follow the included instructions to install the Bridge in a production setting, using either the compiled PHP extension, or a J2EE application server. A standalone version of the Bridge may be run from the command line using JavaBridge.jar (found in the PHP-Java Bridge .war file):

$ java -jar JavaBridge.jar SERVLET:8080 3 javabridge_servlet.log

Replace 8080 with the port on which you wish to run the Bridge. (If running the Indivo Server on the same machine, make sure your ports don't conflict!) Replace 3 with your preferred logging level (7 is the most detailed). The last argument is the full path of your log file location.

Webserver

• Apache 2.0 webserver (not 2.2!)

PHP

• PHP 5.2 or greater
  Note: Older versions of PHP contain a bug that prevents the Java Bridge from properly converting Java objects into PHP objects. If you see strings like "Object id #30" anywhere, you're probably using an old version of PHP.

Your PHP installation must be configured with MySQL support. If you wish to use the graphical growth chart functionality, PHP must also be configured with GD, and FreeType support. None of these extensions are enabled by default.

Your php.ini configuration file also requires some minor tweaking. Whenever a pathname is used, it is just an example.

• In a development setting, it's helpful to display errors on the screen.
  display_errors = On
• In any setting, you ought to log errors to a file.
  error_log = "/var/www/logs/php_errors.log"
• Set your extension directory properly.
  extension_dir = "c:\php\ext"
• To load the pure-PHP Java Bridge include file, you must explicitly allow PHP to include from a URL.
  allow_url_include = On

PHP includes a package manager called PEAR, used for installing third-party tools. Indivo requires the following PEAR packages (with all dependencies):

• DB
• Log (with the mysql dependency as well - not installed by default)
• Config

MySQL

Your webserver must have access to a MySQL database for logging and invitation purposes.

Installation Instructions

• Check out and 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.) For example, if your webserver's documents live at /var/www/html/:

$ tar -xzvf indivo-ui-php-3.0-deploy.tar.gz
$ mv indivo-ui-php-3.0-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. For example, use /usr/local/indivo-php-client/:

$ tar -xzvf indivo-client-php-3.0.tar.gz
$ mv indivo-client-php-3.0 /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 ''
);

Configuration

Apache

If necessary, configure your webserver to point to the directory where you extracted the UI code. Open Apache's httpd.conf file in a text editor. Update the DocumentRoot value and the appropriate <Directory> tag to point to your preferred directory.

PHP Client API

Find apiConfig.xml in the extracted PHP Client directory and open it in a text editor. Fill in the blanks, namely:

• the serverUrl field
• the libraryPath field
• all the logging fields

If your Java Bridge servlet is not running at localhost:8080, open IndivoAPI.class.php in the extracted PHP Client directory, and update line 6 with the correct URL to the Java.inc include file.

User Interface

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.

Secure your administration tools folder! Find htaccess.orig in the UI's admin subdirectory. Rename it to .htaccess and open it in a text editor. It looks like this:

AuthUserFile /usr/local/.htpasswd
AuthName "Authentication Required"
AuthType Basic

<Limit GET POST>
require valid-user
</Limit>

To enable basic HTTP authentication, the first line must point to a valid password file. Create one using the htpasswd utility that ships with Apache, store it outside your web server's document root, and set the AuthUserFile value to the proper path where it's stored.

Testing

Open a browser and visit the server test script included with the UI. If you set up a webserver to run at localhost, then try:

http://localhost/servertest.php

This script will test as many server settings as possible to detect any misconfigurations. If any test fails, you are not ready to use Indivo. Only when all tests say "PASS" should you proceed.

Administrator Configuration

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 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 the UI. If you set up a webserver to run at localhost, then try:

http://localhost/config/setup.php?username=XXXX&password=XXXX

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 (replacing the XXXXs). This is also a good final test of the entire Indivo setup: if it works, you're in great shape.