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.
- 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
Step 2) Install any missing prerequisites
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:
- 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-jdkthe 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 candidateerror, add the following to your
- 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.
- 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:
- 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_02it may be in
Step 3) Set up the database
OPTIONAL: create a file named
/etc/mysql/conf.d/ and put in it:
Restart the database for the new settings to take effect with:
mifostest databases with:
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:
Test the database connection as user 'mifos' with:
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)
- 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/mifostrunkwhich 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.
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.
Step 7) Build Mifos and run integration, unit and acceptance tests
Execute the following:
To skip the tests, execute the following instead of the second line above (much quicker to build):
Step 8) Deploy
Execute the following:
Step 9) Start Mifos
Set up environment variables for Jetty:
Hit CTRL-D to stop writing to .bashrc, then logout/login or source your
~/.bashrc file as follows:
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:
Step 10) Done!
Enjoy your Mifos install - visit http://localhost:8080/mifos/ in a browser (username: "mifos", password: "testmifos").
Install some Development Tools and start fixing some bugs!
If you're seeing time-related failures in the unit tests, you may need to alter your timezone. See this post for details.
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.
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.
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.