Views
Contents
1 Intro
This is an abbreviated guide to help developers get started with Mifos on Ubuntu by building from source. See this guide if you wish to install Mifos using a pre-built war file instead.
The latest version of Ubuntu at the time of writing is 8.04. Fixed-width text below is assumed to be entered (or viewed) in a terminal like gnome-terminal or xterm. This guide applies to Mifos version 1.1 as well as the current development code in the version control system in "trunk".
2 Quick Start
2.2 install prerequisites
Execute the following:
sudo apt-get install sun-java5-jdk ant ant-optional subversion mysql-server
Notes:
- running this command more than once has no effect
- sun-java5-jdk must be installed with ant or installed before, otherwise ant defaults to use the (unsupported) GNU JDK.
Download the latest Tomcat 6.x .tar.gz file (look under Downloads -> Binary distributions -> Core) and unpack it. We'll assume you unpacked Tomcat to $HOME/tomcat6. (Use the tarball instead of apt-get because Mifos requires Tomcat 6.x and the latest version available in Ubuntu is 5.5.)
2.3 set up database
Due to bug 1513, create a file named mifos.cnf in /etc/mysql/conf.d/ and put in it:
[mysqld] lower_case_table_names = 1 innodb_file_per_table
Restart the database for the new settings to take effect
sudo /etc/init.d/mysql restart
Then
- create 'mifos' and 'mifostest' databases
- grant perms to Mifos user (doing these grants more than once has no effect)
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 database connection as user 'mifos'
mysql -u mifos -pmifos mifos
2.4 get the source
with the Subversion Command-line Client
The root of the working copy should be $HOME/mifostrunk, and the root of the Mifos web application source code should be $HOME/mifostrunk/mifos.
2.5 set up the build
In $HOME/mifostrunk/mifos/conf, create a file called my.build.properties with the following contents:
deploy.destination=${env.HOME}/tomcat6/webapps
db.user=mifos
db.pwd=mifos
testdb.name=mifostest
testdb.user=mifos
testdb.pwd=mifos
See conf/build.properties for defaults.
2.5.1 database connection: production
The production database connection must be configured by creating my.hibernate.properties. Start by doing the following:
cd $HOME/mifostrunk/mifos/conf cp hibernate.properties my.hibernate.properties
In my.hibernate.properties, modify only the database username and password as follows:
hibernate.connection.username=mifos hibernate.connection.password=mifos
Now create the tables and load the initial data by executing:
cd $HOME/mifostrunk/mifos ant build_db
2.5.2 database connection: testing
Similarly, create my.HibernateTest.properties to configure the database connection for unit tests:
cp HibernateTest.properties my.HibernateTest.properties
In my.HibernateTest.properties, modify only the database url, username and password as follows:
hibernate.connection.url=jdbc:mysql://localhost:3306/mifostest?useUnicode=true&characterEncoding=UTF-8 hibernate.connection.username=mifos hibernate.connection.password=mifos
2.8 start Mifos
Set up environment variables for Tomcat:
cat >> ~/.bashrc export CATALINA_HOME=$HOME/tomcat6 export JAVA_HOME=/usr/lib/jvm/java-1.5.0-sun
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 ConfiguringMifos. Some configuration must be performed before starting your Mifos instance for the first time.
Now we're ready to start Tomcat. Execute the following:
cd /tmp $HOME/tomcat6/bin/catalina.sh run
Visit http://localhost:8080/mifos/ in a browser to use Mifos. (username: "mifos", password: "testmifos").
Done!
3 Details
3.1 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.
3.2 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.
3.3 Firewalled?
If your machine has a firewall, you need to at least unblock the ports necessary to connect to your Web server. For Tomcat, the default port for serving HTTP traffic is 8080.
3.4 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 mifos.
3.5 Izpack Installer
An installer is also under development.
3.6 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.
4 What Next?
Install some Development Tools and start fixing some bugs!