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

Fixed-width text below is assumed to be entered (or viewed) in a terminal like gnome-terminal or xterm.

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

Step 1) Install Ubuntu

Download and install.

Step 2) Install any missing prerequisites

Java-6 JDK

The default JDK on Ubuntu is OpenJDK 6, which Mifos should support (at least one developer is successfully using soylatte, the OpenJDK 6 port to Mac OS X).

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

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 git-core mysql-server

Notes:

• Running this command more than once has no effect
• If 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
• 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

OPTIONAL: create a file named mifos.cnf in /etc/mysql/conf.d/ and put in it:

[mysqld]
# optional, but saves disk space
innodb_file_per_table

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

sudo service mysql restart

Then create mifos and mifostest databases with:

• ~$ 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:

  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 the database connection as user 'mifos' with:

  mysql -u mifos -pmifos mifos

Step 4) Get the source

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.

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 /db/src/main/resources/sql/, not /db/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 can be configured by customizing the following settings in your Local Properties File.

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:

cd $HOME/mifostrunk
mvn clean install

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

mvn clean install -Dmaven.test.skip=true

Step 8) Deploy

Execute the following:

cd $HOME/mifostrunk/war
cp target/mifos.war $HOME/jetty7/webapps/mifos.war

Step 9) Start Mifos

Set up environment variables for Jetty:

cat >> ~/.bashrc
export JETTY_HOME=$HOME/jetty7
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:

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 Jetty. Execute the following:

cd /tmp
$HOME/jetty7/bin/jetty.sh start

Step 10) Done!

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

Additional Details

What next?

Install some Development Tools and start fixing some bugs!

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.

Firewalled?

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

Debian Package

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

Still can't connect to MySQL?

Ensure that a TCP listening socket is active; ensure "skip-networking", if extant, is commented out of the config file.

Running 64-bit Ubuntu?

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 JDK can be built if needed.

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.