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.

...

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:

...

• Mifos currently requires Jetty 7.3.x - download the relevant Jetty tarball from from http://downloadarchive.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      {{8" in the Connector definition.

...

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

...

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

  No Format
  mysql -u mifos -pmifos mifos

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.

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

...

Database connections 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:

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/mifoswar
cp target/mifos_webapp.war $HOME/jetty7/webapps/mifos.war

Step 9) Start Mifos

Set up environment variables for Jetty:

...

cd /tmp
$HOME/jetty7/bin/jetty.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!

Details

...

...

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.

...

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.

What next?

Install some Development Tools and start fixing some bugs!. See this page for PermGen Out of Memory errors specifically.