Intro
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.
Quick Start
Install Ubuntu
Install 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-get install sun-java6-jdk git-core mysql-server
Notes:
- running this command more than once has no effect
- You can make
sun-java6-jdk
the default for your applications by executing
sudo update-java-alternatives -s java-6-sun
Jetty 7
Mifos requires Jetty 7.x. Download Jetty tarball from http://download.eclipse.org/jetty/ 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 bundled instructions. The "mvn" command must be on your path. The version of Maven we currently recommend is found on Developer Setup.
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.
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.
sudo service mysql restart
Then
- Create
mifos
andmifostest
databases. Use:~$ 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 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 database connection as user 'mifos'
mysql -u mifos -pmifos mifos ...repeat for other databases
Get the source
This page shows you how.
The root of the working copy should be $HOME/mifostrunk
.
Create production tables
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/. INSTALL is really for war-only installs (not developers).
Set up the build - Mifos
Create a Local Properties File.
Database connections
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
Build Mifos and run integration, unit and acceptance tests
Execute the following:
cd $HOME/mifostrunk mvn clean install
Deploy
Execute the following:
cd $HOME/mifostrunk/mifos cp target/mifos_webapp.war $HOME/jetty7/webapps/mifos.war
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
Visit http://localhost:8080/mifos/
in a browser to use Mifos. (username: "mifos", password: "testmifos").
Done!
Details
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.
What Next?
Install some Development Tools and start fixing some bugs!