Table of Contents | ||
---|---|---|
|
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.
...
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 8.10 is OpenJDK 6, which Mifos should support (at least one developer is successfully using soylatte, the OpenJDK 6 port to Mac OS X)
...
sudo update-java-alternatives -s java-6-sun
Tomcat 6
Mifos requires Tomcat 6.x. Ubuntu 8.10 installs the tomcat6 package, but as of fall, 2008 the package was buggy. Earlier versions of Ubuntu come with Tomcat 5.5, which Mifos no longer supports. Mifos is also not able to work with the Ubuntu Tomcat package in Ubuntu 9.04. We recommend installing Tomcat 6 from a downloaded tarball, but here is a link about how to get the Ubuntu Tomcat package to work on Ubuntu 9.04.
Download the latest Tomcat 6.x archive (look under Downloads → Binary distributions → Core) and unpack it. In the instructions that follow, we'll assume you unpacked Tomcat to $HOME/tomcat6
. If you've put it somewhere else, adjust accordingly.
Maven 2
Maven 2.0.9 or later is required. Download the latest Maven 2.x binary and install following bundled instructions. The "mvn" command must be on your path.
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
If you are building/deploying a Mifos version prior to 1.6.0, you must work around issue 1513. Create a file named mifos.cnf
in /etc/mysql/conf.d/
and put in it:
...
- Create
mifos
andmifostest
databases. Use: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 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 database connection as user 'mifos'
No Format 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 application/src/main/sql
. INSTALL assumes you have a release .zip file, with SQL files in sql
.
Set up the build - Mifos
Create a Local Properties File.
database connections
Database connections must 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 |
Build Mifos and run integration, unit and acceptance tests
Execute the following:
No Format |
---|
cd $HOME/mifostrunk mvn clean install |
Deploy
Execute the following:
No Format |
---|
cd $HOME/mifostrunk/mifos cp target/mifos_webapp.war $HOME/tomcat6/webapps/mifos.war |
Start Mifos
Set up environment variables for Tomcat:
...
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.
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.
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.
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
.
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|http://java.dzone.com/tips/32-bit-jdk-a-64-bit-ubuntu-sys] if needed.
What Next?
Install some Development Tools and start fixing some bugs!