Installing ClearHealth From Subversion

From OpenWiki

This guide is designed to help someone install ClearHealth.

Currently, the best way to insure you are using the latest version of ClearHealth is to install it from our Subversion server. The following instructions will help you through the installation process.

1 Requirements
2 Initial Checkout
3 Initial Configuration
4 Maintaining an Subversion installation
- 4.1 Running svn update
- 4.2 Updating the database

[edit] Requirements

You will need the following software tools installed on your server in order to complete the installation process.

Subversion 1.2+
Apache
PHP 4.3+
- MySQL extension
- GD extension
MySQL 4.1

Downloading and configuring these software programs is beyond the scope of this tutorial. Please refer to the documentation of each for information on downloading and installing them.

[edit] Initial Checkout

You can install ClearHealth in any location that your server is setup to serve it from. This tutorial will use the default location for Ubuntu, /var/www.

There are two repositories that contain all of the code required for to run ClearHealth, the ClearHealth repository at http://svn.op-en.org/svn/clearhealth and the Celini repository at http://svn.op-en.org/svn/celini. In order to checkout ClearHealth, Celini, and it's required modules, you would run the following svn commands.

cd /var/www
svn checkout http://svn.op-en.org/svn/clearhealth/clearhealth/trunk/ clearhealth
svn checkout http://svn.op-en.org/svn/celini/trunk clearhealth/celini
svn checkout http://svn.op-en.org/svn/clearhealth/billing/trunk/ clearhealth/modules/billing
svn checkout http://svn.op-en.org/svn/clearhealth/calendar/trunk/ clearhealth/modules/calendar
svn checkout http://svn.op-en.org/svn/clearhealth/labs/trunk/ clearhealth/modules/labs
svn checkout http://svn.op-en.org/svn/clearhealth/x12_importer/trunk/ clearhealth/modules/x12_importer

[edit] Initial Configuration

ClearHealth has a configuration file located at /var/www/clearhealth/local/config.php that must be created. A sample configuration file is provided /var/www/clearhealth/local/config.php.dist. This can be used as the base for creating your own config.php file

cd /var/www/clearhealth
cp local/config.php.dist local/config.php

[edit] Editing Database Configuration

You will need to provide the proper configuration values in order to ClearHealth to locate the database. To do this, edit your newly created local/config.php file and locate the following block of code:

################################################################################
# Database Setup
################################################################################
$config['db_type'] = "mysql";
$config['db_host'] = "INSTALL_DB_SERVER";
$config['db_user'] = "INSTALL_DB_USERNAME";
$config['db_password'] = "INSTALL_DB_PASSWORD";
$config['db_name'] = "INSTALL_DB_DATABASE";
$config['db_table_prefix'] = "";

You will want to replace all of the INSTALL_DB_* values with the appropriate values for your database server's configuration. A completed sample might look like:

################################################################################
# Database Setup
################################################################################
$config['db_type'] = "mysql";
$config['db_host'] = "localhost";
$config['db_user'] = "clearhealth_user";
$config['db_password'] = "SuperSecret";
$config['db_name'] = "clearhealth";
$config['db_table_prefix'] = "";

[edit] Database Setup

Information below this point currently being worked on and may have contradictory information

You will then need to install the database and tables. We will be working under the assumption that you are using the database name clearhealth

mysqladmin create clearhealth

Once the database is created, you will need to import the structure and basic data required for to run ClearHealth

mysql -u root clearhealth < /path/to/clearhealth/local/setup/clearhealth-1.0RC3.sql
mysql -u root clearhealth < /path/to/clearhealth/local/setup/clearhealth-1.0RC3-data.sql

Currently, the RC3 file is not 100% up-to-date. It will be updated prior to the next release. In the meantime, we will need to run the files located in the local/setup/updates directory from May 25th onward to insure we are running the latest version.

[edit] Directory permissions

There are two directories that need to be writable by Apache for ClearHealth to work properly. tmp and user. The easiest way to allow this is to make your Apache user the owner.

Apache Owned

chown www-data tmp user

The actual user, www-data in this example, may change depending on which distribution you are using. Refer to your distribution's documentation if you are unsure what user Apache runs as.

[edit] tmp directory

The tmp directory stores all of the compiled templates from Smarty within the system and other miscellaneous files that need to be created in a temporary form.

[edit] user directory

The user directory stores data that needs to be kept in some sort of persistant storage. Documents that are attached to patients, report templates, etc., are stored within this directory.

[edit] Maintaining an Subversion installation

Once you have your Subversion installation setup, all that is required to keep it current it to run svn update and apply the occassional SQL patch file.

[edit] Running svn update

There are six repositories that must be updated, these can be done individually or in a batch. To keep the commands shorter, all of these commands are being run as if you are in /var/www/clearhealth

Individually

svn update
svn update celini
svn update modules/billing 
svn update modules/calendar
svn update modules/labs
svn update modules/x12_importer

Combined
A more common option would be to update all of the files that have been checked out in a combined command.

svn update celini modules/billing modules/calendar modules/labs modules/x12_importer .

[edit] Updating the database

From time to time, changes are made to the database to accomodate new features. Each change is stored in the local/setup/updates directory as an SQL file with the following file format:

YYYY-MM-DD_table_name.sql

So for example, a file that updates the person table that was committed on June 14th, 2006 would be named:

local/setup/updates/2006-06-14_person.sql

As the changes come in, you will want to apply them immediately after updating, otherwise the new features you have just installed via svn update will not work properly.