Table of Contents

outline	true

Introduction

This is an abbreviated guide for Ubuntu-based developers who want to build Mifos from source. See Ubuntu WAR Install if you wish to install Mifos using a pre-built war file instead.

This guide:

is written for Ubuntu 810.10 04 for the 32-bit x86 architecture, but may work on other versions
attempts to call out steps required for different versions of Ubuntu
applies to the current Mifos development code in the version control system in "trunk"

...

Please give feedback on any discrepancies or needed additions or corrections to the developer mailing list.

Quick Start

Step 1) Install Ubuntu

Download and install.

Step 2) Install any missing prerequisites

Java-6 JDK

The default JDK on Ubuntu 8.10 is OpenJDK 6, which Mifos should support (at least one developer is successfully using soylatte, the OpenJDK 6 port to Mac OS X)Ubuntu 8.04's JDK is GNU JDK which Mifos does not support. Earlier versions use Java-5 which Mifos also no longer supports. In either case you need to install .

Oracle/Sun Java-6 JDKis what we recommend for production, so it's the best bet for development, too. Execute the following:

No Format
sudo apt-add-repository ppa:flexiondotorg/java sudo apt-get update sudo apt-get install sun-java6-jdk sun-java6-plugin sudo apt-get install sun-java6-jdk subversiongit-core mysql-server

Notes:

running Running this command more than once has no effect
sun-java6-jdkIf you want to list which Java versions are already installed, execute the following:
sudo update-java-alternatives -l
You can make sun-java6-jdk the default for your applications by executing the following:
sudo update-java-alternatives -s java-6-sun

Tomcat 6

Mifos requires Tomcat 6.x. Ubuntu 8.10 installs the tomcat6 package, but as of fall, 2008 the package was buggy. Earlier versions of Ubuntu come with Tomcat 5.5, which Mifos no longer supports. Mifos is also not able to work with the Ubuntu Tomcat package in Ubuntu 9.04. We recommend installing Tomcat 6 from a downloaded tarball, but here is a link about how to get the Ubuntu Tomcat package to work on Ubuntu 9.04.

...

If you see the Package sun-java6-jdk has no installation candidate error, add the following to your /etc/apt/sources.list file:
deb http://us.archive.ubuntu.com/ubuntu/ hardy multiverse

Jetty 7

Mifos currently requires Jetty 7.3.x - download the relevant Jetty tarball from http://archive.eclipse.org/jetty/7.3.1.v20110307/dist/ and unpack it.
In the instructions that follow, we'll assume you unpacked

...

Jetty to $HOME/

...

jetty7. If you've put it somewhere else, adjust accordingly.
If using extended characters, be sure server configuration includes URIEncoding="UTF-8" in the Connector definition.

Maven

...

...
Download
...
Maven
...
and install following
...
the binary instructions. The version of Maven we currently recommend is found on Developer Setup.
The "mvn" command must be on your path. You can verify that it is correctly installed by executing the following:
`mvn --version`
Notes:
If you run into 'java.lang.OutOfMemoryError: Java heap space' during mvn's e.g. javac invocation, an "export MAVEN_OPTS=-Xmx512m" helps, best appended to your ~/.profile file.
Your JAVA_HOME path may be different than the one listed in the Maven installation instructions e.g. instead of `/usr/java/jdk1.5.0_02` it may be in `user/lib/jvm`

Step 3) Set up the database

If you are building/deploying a Mifos version prior to 1.6.0, you must work around issue 1513. Create a OPTIONAL: create a file named mifos.cnf in /etc/mysql/conf.d/ and put in it:

No Format
[mysqld] # due to issue 1513 lower_case_table_names = 1 # optional, but saves disk space innodb_file_per_table

Restart the database for the new settings to take effect .with:

No Format
sudo /etc/init.d/service mysql restart

Then

...

create mifos and mifostest databases

...

with:

No Format

~$ mysql -u root -p
mysql> CREATE DATABASE mifos;
mysql> CREATE DATABASE mifostest;
mysql> show databases;
+--------------------+
| Database           |
+--------------------+
| information_schema |
| mifos              |
| mifostest          |
| mysql              |
+--------------------+

Grant permissions to user 'mifos' (doing these grants more than once has no effect). If you want to choose a different user name and password, adjust these instructions accordingly:
No Format
mysql> GRANT ALL on mifos.* to 'mifos'@'localhost' identified by 'mifos'; mysql> GRANT ALL on mifostest.* to 'mifos'@'localhost' identified by 'mifos'; mysql> FLUSH PRIVILEGES;

test

Test the database connection as user 'mifos' with:

No Format
mysql -u mifos -pmifos mifos ...repeat for other databases

Step 4) Get the source

This page shows The Mifos Version Control Guide shows you how.

Based on its contents, ensure that you have:

Told Git to handle line endings
Set your Author Information correctly (specifically, name and email)

Note:

You can skip the Git install step on the instructions, as this was installed at the start of this tutorial
The root of the working copy should be $HOME/mifostrunk which you can do with the following command:
git clone git://github.com/mifos/head.git mifostrunk

Step 5) Create production tables

After obtaining your personal copy of the source code and configuring your database you need to create production tables. In order to do that you need to execute following commands.

No Format

mysql -u mifos -pmifos mifos < $HOME/mifostrunk/db/src/main/resources/sql/base-schema.sql
mysql -u mifos -pmifos mifos < $HOME/mifostrunk/db/src/main/resources/sql/base-data.sql
mysql -u mifos -pmifos mifos < $HOME/mifostrunk/db/src/test/resources/sql/acceptance_test_dump.sql
mysql -u mifos -pmifos mifos < $HOME/mifostrunk/db/src/main/resources/sql/init_mifos_password.sql

OR

See "Initializing the Mifos Database" in $HOME/mifostrunk/INSTALL, with one exception: the SQL files in your working copy are in application/db/src/main/resources/sql/, not /db/sql/. INSTALL assumes you have a release .zip file, with SQL files in sql.

The INSTALL file is really for war-only installs (not developers building from source).

Step 6) Set up the build

...

Create a Local Properties File.

...

Database connections must can be configured by customizing the following settings in your Local Properties File:.

No Format

main.database=mifos
main.database.user=mifos
main.database.password=mifos
integration.database=mifostest
integration.database.user=mifos
integration.database.password=mifos
acceptance.database=mifostest
acceptance.database.user=mifos
acceptance.database.password=mifos

Step 7) Build Mifos and run integration, unit and acceptance tests

Execute the following:

No Format
cd $HOME/mifostrunk mvn clean install

To skip the tests, execute the following instead of the second line above (much quicker to build):

No Format
mvn clean install -Dmaven.test.skip=true

Step 8) Deploy

Execute the following:

No Format
cd $HOME/mifostrunk/mifoswar cp target/mifos_webapp.war $HOME/tomcat6jetty7/webapps/mifos.war

Step 9) Start Mifos

Set up environment variables for TomcatJetty:

No Format
cat >> ~/.bashrc export CATALINAJETTY_HOME=$HOME/tomcat6jetty7 export JAVA_HOME=/usr/lib/jvm/java-6-sun export JAVA_OPTIONS="-Xms1024M -Xmx1024M -XX:MaxPermSize=256m"

Hit CTRL-D to stop writing to .bashrc, then logout/login or source your ~/.bashrc file as follows:

No Format
source ~/.bashrc

If this is a production system, be sure to thoroughly read Configuring Mifos. Some configuration must be performed before starting your Mifos instance for the first time.

Now we're ready to start TomcatJetty. Execute the following:

No Format
cd /tmp $HOME/tomcat6jetty7/bin/startupjetty.sh start

...

Step 10) Done!

Enjoy your Mifos install - visit http://localhost:8080/mifos/ in a browser to use Mifos. (username: "mifos", password: "testmifos").Done

...

Additional Details

What next?

Install some Development Tools and start fixing some bugs!

...

Timezone Fix

Timezone fix

If you're seeing time-related failures in the unit tests, you may need to alter your timezone. See this post for details.

Tomcat cd to /tmp

In the last step of the quick start guide, you may notice that we actually change to the /tmp directory before starting Tomcat. This is because (currently) the Mifos log writer is somewhat broken and writes a logfile to the current directory. Changing to /tmp avoids cluttering up other directories. Also, in Ubuntu, /tmp is automatically cleaned up on reboot.

Firewalled?

If your machine has a firewall, you need to at least unblock the ports necessary to connect to your Web server. For TomcatJetty, the default port for serving HTTP traffic is 8080.

Debian Package

The installation steps are fairly simple and could probably be a single Bash shell script. Or even a deb package Imagine this whole install guide being replaced with simply sudo apt-get install mifosThere is a shell script to help Ubuntu users install Mifos. See application/release/install-ubuntu.sh in the head repository. There's also a script to build a debian package that works fairly well, it's called resources/linux/build_deb_package.sh. If you are interested in helping us further improve our debian package, please see the volunteer project page.

Security and Encryption

Mifos v1.1 provides no encryption and little security. Current discussion appears to recommend securing HTTP traffic over SSL, and possibly also using a VPN.

...

Use 32-bit Java. While Using a 64-bit Java VM appears to increase Mifos memory requirements. On Ubuntu, a 32-bit Sun JRE is pre-built (the ia32-sun-java6-bin package), and `a a JDK can be built|http://java.dzone.com/tips/32-bit-jdk-a-64-bit-ubuntu-sys] if needed.

What Next?

...

Memory errors?

If you've correctly set your environment variables for Maven (MAVEN_OPTS) and Java (JAVA_OPTIONS), as above, but you're still seeing memory issues when using Mifos, you may need to increase the size of your swap file / partition. See this page for PermGen Out of Memory errors specifically.

Versions Compared

Old Version 9

New Version Current

Key

Introduction

Quick Start

Step 1) Install Ubuntu

Step 2) Install any missing prerequisites

Java-6 JDK

Tomcat 6

Jetty 7

Maven

Step 3) Set up the database

Step 4) Get the source

Step 5) Create production tables

Step 6) Set up the build

Step 7) Build Mifos and run integration, unit and acceptance tests

Step 8) Deploy

Step 9) Start Mifos

Step 10) Done!

Additional Details

What next?

Timezone Fix

Timezone fix

Tomcat cd to /tmp

Firewalled?

Debian Package

Security and Encryption

What Next?

Memory errors?

Page Comparison

Versions Compared

Old Version 9

New Version Current

Key

Introduction

Quick Start

Step 1) Install Ubuntu

Step 2) Install any missing prerequisites

Java-6 JDK

Tomcat 6

Jetty 7

Maven

Step 3) Set up the database

Step 4) Get the source

Step 5) Create production tables

Step 6) Set up the build

Step 7) Build Mifos and run integration, unit and acceptance tests

Step 8) Deploy

Step 9) Start Mifos

Step 10) Done!

Additional Details

What next?

Timezone Fix

Timezone fix

Tomcat cd to /tmp

Firewalled?

Debian Package

Security and Encryption

What Next?

Memory errors?