Contents

• 1 Contents
• 2 Purpose
• 3 Installation of Mifos on Red Hat Enterprise Linux 5
• 3.1 Application Server Installation (JBoss or Tomcat)
  
• 3.2 Database Installation
• 3.3 Mifos Application Deployment
• 4 Installation of Mifos on Red Hat Enterprise Linux 4

Purpose

This document guides the audience on the deployment of the Mifos application on Intel x86 Linux (Red Hat EL5/EL4), using jboss-4.2.1 or Tomcat-6.0.16 as application server and MySQL 5.0 as the database. The Mifos WAR used is built from SVN revision 12249. The application server and the database server are co-located on the same machine.

CentOS may be used in place of Red Hat Enterprise Linux if operating system license cost is a problem.

Conventions

Bash commands

Commands run as a non-root user on the Bash command line are in a monospace font and preceeded by a dollar sign, like so:

$ ls -l /tmp

It is safe to assume that the non-root user is "mifos" belonging to group "mifos". Commands should be typed in without the dollar sign.

Bash commands as Root

Commands run as root are in a monospace font and preceeded by a hash, like so:

# /etc/init.d/mysql restart

At this point the administrator has assumed root privileges with, for instance:

$ su -

If available, sudo may also be used to execute commands that require root privileges. For example:

$ sudo /etc/init.d/mysql restart

MySQL commands

Commands executed on the MySQL client prompt are indicated as follows:

mysql> select * from database_version;

Your IP Address

Your server's IP address will be represented as "xxx.xxx.xxx.xxx".

Installation of Mifos on Red Hat Enterprise Linux 5

Application Server Installation (Tomcat)

Install and configure Java

Download the Sun JDK 5.0 Update XX from java.sun.com. Look for "Linux RPM in self-extracting file": jdk-1_5_0_XX-linux-i586-rpm.bin, where XX is the latest released version. 1.5.0_14 is the most recent version at the time of writing. In the following sections, "XX" should be substituted for the specific release you downloaded.

Place the .bin file in the /tmp directory.

Change directory to where the downloaded file is located, make the self-extracting file executable, then execute it:

$ cd /tmp
$ chmod +x jdk-1_5_0_XX-linux-i586-rpm.bin
$ ./jdk-1_5_0_XX-linux-i586-rpm.bin

The script displays a license agreement, which you are asked to agree to before installation can proceed. Once you have agreed to the license, the install script creates the file jdk-1_5_0_XX-linux-i586.rpm in the current directory.

# rpm -Uvh jdk-1_5_0_13-linux-i586.rpm

Install convenience symlink to what will become JAVA_HOME:

# cd /usr/java
# ln -s jdk1.5.0_XX sun

Set up the mifos user

Create a user that will execute the Mifos application server:

# useradd mifos

Set and export PATH and JAVA_HOME in the mifos user's environment. As the mifos user, execute:

$ cat >> ~/.bash_profile

Then type or paste in the following text (will be written to ~/.bash_profile):

export JAVA_HOME=/usr/java/sun
export JBOSS_HOME=$HOME/jboss
export CATALINA_HOME=$HOME/tomcat6/apache-tomcat-6.0.16
export PATH=$HOME/bin:$PATH

Hit CTRL-D to stop writing to the ~/.bash_profile. If you pasted the text, make sure no spurious characters were introduced.

Source your Bash profile to obtain the new environment settings:

$ . ~/.bash_profile

Set up a symlink for the java executable:

$ mkdir -p ~/bin
$ cd ~/bin
$ ln -s /usr/java/sun/bin/java
$ ln -s /usr/java/sun/bin/javac

Install Tomcat

Download the stable version 6.0.16 (or higher) of Tomcat for Unix from http://tomcat.apache.org/download-60.cgi .Click on Tomcat6.x link on the left side and download the CORE and the DEPLOYER choosing the format ta.gz from BINARY DISTRIBUTION section.

See the following link for more information on about to setup Tomcat 6 :

http://tomcat.apache.org/tomcat-6.0-doc/setup.html

We do not describe how to set as Unix daemon.

Copy the tar.gz archive to /tmp directory.

Install Tomcat CORE into /home/mifos/tomcat as follows:

$ mkdir /opt/tomcat6
$ cd /opt/tomcat6
$ unzip /tmp/apache-tomcat-6.0.16.tar.gz
$ tar -xvf apache-tomcat-6.0.16.tar
$ ln -s apache-tomcat.60.16 tomcat (may be does not serve)

Verify that in the /opt/tomcat6 you have the Tocat 6 package

expanded.
Check the startup:

cd /opt/tomcat6/apache*/bin/.startup.sh

apache* is the way to shorten apache-tomcat-6.0.16 (or upper)

Install Tomcat DEPLOYER:

Installing TOMCAT-Deployer will allow remote deployment.

$ cd /opt/tomcat6
$ unzip /tmp/apache-tomcat-deployer-6.0.16.tar.gz
$ tar -xvf apache-tomcat-deployer-6.0.16.tar
$ ln -s apache-tomcat-deployer-60.16 tomcat-deployer (may be does not serve)

Edit catalina.sh for standard settings:

Just at the beginning of the scripts add if you want verbose garbage collector and settings for heap size (initial and maximum):

JAVA_OPTS= "$JAVA_OPTS" "-verbose:gc -XX:+PrintGCDetails -XX:+PrintGCTimeStamps -Xloggc:$CATALINA_HOME\logs\gc.log -Xms128M -Xmx512M"

$CATALINA_HOME should point to /opt/tomcat6/apache-tomcat-6.0.16 directory.

Verify with the command:

echo $CATALINA_HOME

Start Tomcat 6

Run the following command:

cd $CATALINA_HOME/bin

./startup.sh

Test Tomcat 6 Installation

Open a browser and type the following URL:

http://localhost:8080

If the page of Tomcat appears the installation has been successfully completed.

Install Ant

$ cd ~
$ unzip /tmp/apache-ant-1.7.0-bin.zip
$ ln -s apache-ant-1.7.0 ant
$ cd ~/bin
$ ln -s ~/ant/bin/ant

Database Installation

Install MySQL

Download MySQL RPMs for your particular OS and architecture from http://dev.mysql.com/downloads/mysql/5.0.html. You'll need the following packages:

1. Server
2. Client
3. Shared libraries

Install the RPMs like so:

# rpm -Uvh MySQL*.rpm

Configure MySQL

Add the following entries to /etc/my.cnf under the [mysqld] section:

lower_case_table_names=1
innodb_file_per_table

The lower_case_table_names setting is required until issue 1513 is fixed. See here for more information on this setting: http://dev.mysql.com/doc/refman/5.1/en/identifier-case-sensitivity.html

The InnoDB setting helps control Mifos tablespace size on disk. See this mailing list post for more information.

The bind-address setting may also need adjusting. If bind-address is set to 127.0.0.1, only local connections are allowed. If the machine has two or more network cards, bind-address should be set to the desired IP address.

Restart the MySQL server using the MySQL Administrator:

# /usr/share/mysql-gui/mysql-administrator

or via the command-line startup script installed as part of the MySQL RPMs:

# /etc/init.d/mysql restart

Mifos Application Deployment

Get the Source Code

Follow instructions here.

Prepare MySQL database for Mifos

$ mysql -u root -p<password>
mysql> create database mifos;
mysql> GRANT ALL ON mifos.* TO mifosdbuser IDENTIFIED BY 'xxx';

Substitute xxx for the password of your choice.

Prepare for build

At this stage you must create files in the $HOME/mifostrunk/mifos/conf directory to match your deployment.

Create $HOME/mifostrunk/mifos/conf/my.build.properties with the following content, substituting XXX for the 'mifosdbuser' password:

db.name=mifos
db.ip=localhost
db.port=3306
db.user=mifosdbuser
db.pwd=XXX
deploy.destination=${env.HOME}/bin/tomcat5.5/webapps/

Create $HOME/mifostrunk/mifos/conf/my.hibernate.properties with the following content, substituting XXX for the 'mifosdbuser' password:

hibernate.connection.driver_class=com.mysql.jdbc.Driver
hibernate.connection.url=jdbc:mysql://localhost:3306/mifos?useUnicode=true&characterEncoding=UTF-8
hibernate.connection.username=mifosdbuser
hibernate.connection.password=XXX
hibernate.dialect=org.hibernate.dialect.MySQLDialect
hibernate.show_sql=false
hibernate.transaction.factory_class=org.hibernate.transaction.JDBCTransactionFactory
hibernate.cache.provider_class=org.hibernate.cache.HashtableCacheProvider
hibernate.connection.isolation=2

Initialize Mifos database

$ cd ~/mifostrunk
$ ant build_db

Build/deploy Mifos WAR

$ cd ~/mifostrunk
$ ant deploy

Start Tomcat

$ cd $CATALINA_HOME/bin && ./startup.sh --host xxx.xxx.xxx.xxx

Open a browser to http://xxx.xxx.xxx.xxx:8080/mifos to use Mifos.

username: mifos

password: testmifos

Installation of Mifos on Red Hat Enterprise Linux 4

Follow all instructions above substituting "rhel4" in place of "rhel5" when downloading and installing MySQL RPMs.