Home

mifosx

This page lists out the instructions for getting started on mifosx for Developers.

Github & Git

Fork the project on your personal github account.

If you dont have a github account already then you need to sign up and create one on on github.com (free accounts are fine).

Once you have a github account, the next step is to fork https://github.com/keithwoodlock/mifosx.

see https://help.github.com/articles/fork-a-repo for help on forking in github.

Clone the repository to your local machine.

Create a directory in which you want the cloned project to exist within: e.g. in directory c:/dev/githubrepos/

git clone [fork repository url]

For example: [email protected]:USERNAME/mifosx.git

see https://help.github.com/articles/fork-a-repo for help on forking in github

see https://help.github.com/articles/which-remote-url-should-i-use

You should have a directory structure like the following:

mifosx:

• mifosng-db
• mifosng-provider

Configure remotes

When a repository is cloned, it has a default remote called origin that points to your fork on GitHub, not the original repository it was forked from. To keep track of the original repository, you need to add another remote named upstream:

git remote add upstream [email protected]:keithwoodlock/mifosx.git

Pull in upstream changes

To pull in upstream changes from repository you forked:

git fetch upstream

git rebase upstream/master

Note: the use of rebase for pulling in changes on top of your possible local dev changes as opposed to merge.

Read more about this at http://help.github.com/fork-a-repo/

Gradle Setup

Gradle 1.0 or later Installed

Download gradle from www.gradle.org, be sure to following instructions for installation at http://gradle.org/docs/current/userguide/installation.html

Test gradle installation:

gradle -version

This should output some information about version of gradle you are using. It must be the 1.0 release version at a minimum.

Important environment variables of interest:

GRADLE_HOME e.g. C:\dev\gradle-1.0

JAVA_HOME e.g. C:\dev\java\jdk6_u30

JAVA_OPTS e.g. -Xms512m -Xmx512m -XX:MaxPermSize=512m

Configure gradle.bat or gradle.sh to support remote debugging

In GRADLE_HOME/bin, edit the gradle.bat/gradle.sh (depending on OS) and update the line near top of file from

set DEFAULT_JVM_OPTS=

to

set DEFAULT_JVM_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,address=8005,server=y,suspend=n

Note: This is better than putting remote debugging JVM parameters into JAVA_OPTS.

Eclipse Setup

Instructions for using eclipse for development on mifosx.

Eclipsify your application

• Move into the mifosng-provider directory.

Execute the following: gradle clean cleanEclipse eclipse

when this finishes do gradle clean war

Note: gradle tasks shows all tasks that can be executed in each directory.

Import project into eclipse

Create a new directory for your eclipse workspace. e.g. c:/dev/eclipse-workspaces/mifosx-github

Start up Eclipse (assuming its already installed)

Use the workspace directory you just created.

When opened, in the package explorer of the java perspective, right-click import->General->Existing projects into workspace. In the dialog that opens, specify the root directory option by browsing to and selecting the mifosx directory that was cloned e.g. c:/dev/githubrepos/mifosx

This show pick up on the mifosng-provider project you just 'eclipsified' in last step. Click Finish to import into workspace.

Note: You may see eclipse warning to do with 'Serializable'. Goto Window->Preferences->Java->Compiler->Errors/Warnings. In the Potential programming problems section choose 'ignore' for 'Serializable class without serialVersionUID:' option.

Remote debugging through eclipse

On the debugger (see menu icon that looks like a bug/spider), choose Debug configurations...

Database setup

Assuming you already have a version of MySql installed. To get started quickly you can just setup the latest demo database.

Mifos X has support for hosting multiple tenants.

Create schema/database named mifosplatform-tenants

create database 'mifosplatform-tenants';

Then apply file; mifosng-db/multi-tenant-demo-backups/0001-mifos-platform-shared-tenants.sql

mysql -u[user] -p[password] mifosplatform-tenants < mifosng-db/multi-tenant-demo-backups/0001-mifos-platform-shared-tenants.sql

Create schema/database named mifostenant-default.

create database 'mifostenant-default';

Then apply file; mifosng-db/multi-tenant-demo-backups/mifostenant-default.backup.sql to this database;

mysql -u[user] -p[password] mifostenant-default < mifosng-db/multi-tenant-demo-backups/mifostenant-default.backup.sql

Launching mifosx from command line.

Note: When launching the platform from the command line for developement, the user/password used for the database is root/mysql. If your root user password for mysql is different, you should change the password in the file mifosng-provider/src/test/resources/META-INF/context.xml

Open up a terminals or command prompt.

On terminal, move into the mifosng-provider directory and execute gradle clean tomcatRunWar

If all has gone well, the platform should be available at: https://localhost:8443/mifosng-provider/api/v1/offices?tenantIdentifier=default

For client applications built on top of the platform see the mifosx-community-apps repository.

You should be able to log into platform with Username: mifos and Password: password.

Troubleshooting Help

BindException Errors

If you get the java.net.BindException: Address already in use :8080 exception whilst running the gradle command inside the mifosng-individual-lending-app directory, you may need to kill the process which is already using 8080 (netstat -aon | grep 8080).