-
Notifications
You must be signed in to change notification settings - Fork 0
Home
This page lists out the instructions for getting started on mifosx for Developers.
We use Github & Git as we want:
- To simplify the way individuals and organisations can get access to the source code of our software.
- Allow individuals and organisations to independently make changes and extend the software for their own needs
- Allow individuals and organisations to easily contribute back any work they do through the Fork & Pull model.
Developers should follow the instructions below to make the above possible.
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.
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
After the clone operation has completed (should be pretty quick), you should have a directory structure like the following:
mifosx:
- mifosng-db
- mifosng-provider
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 should add another remote named upstream:
git remote add upstream [email protected]:keithwoodlock/mifosx.git
Its probably easiest if you create a new 'topic' branch on your forked repository for each unique piece of work rather than commit changes directly into master. Why?
It means you can work on something very specific, get it up to date and send a 'pull request', To move on to a seperate piece of work, you simply create a different branch. It might also make it easier to keep up to date with the keithwoodlock/mifosx repository as explained in next section.
There will be development changes to the keithwoodlock/mifosx almost every day for the foreseeable future so its important to keep your fork of the software up to date with the latest changes.
To pull in upstream changes from repository you forked:
git checkout master ... to make sure you are on the master branch
git fetch upstream ...fetches changes from upstream respository but does not merge/rebase them
git merge upstream/master ... merge in the new changes from upstream/master repository into your repository and branch (should be master)
git checkout my-topic-branch ... switch to the topic branch you are using for piece of development work
git rebase master ... rebase your topic branch which means, take in all latest changes and replay your work in topic branch on top of this - this produces cleaner versions/history
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/
git push origin [branchname] e.g. git push origin master
We would expect people to use the Fork & Pull model for collaborating back. Simply this means that we expect you to use Githubs tools here and to send pull-requests to us when you have a piece of work you want to contribute back.
Read more here: https://help.github.com/articles/using-pull-requests
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
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.
Instructions for using eclipse for development on mifosx.
- 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.
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.
On the debugger (see menu icon that looks like a bug/spider), choose Debug configurations...
- Select Remote Java Application from list of configurations and click the icon on top for New launch configuration
- For name enter something like: Remote debug mifosx platform
- In connect tab, ensure the following
- project: mifosng-provider
- Host: localhost
- Port: 8005 (or whatever you chose when adding remote debugging paramaters in the setting up gradle section)
- In common tab, tick of dispay in favourites for Debug
Apply/Save these changes and select the saved launch configuration from your debug menu to attach the debugger to the already running mifosx platform (if the platform isnt running you will get message from eclipse saying it cant attach to JVM etc)
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
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
Also, you want to update the schema settings associated with each entry in the mifosplatform-tenants database:
Example of updating tenant with id 1 to use mifos/mifos as username/password for database connections.
UPDATE mifosplatform-tenants.tenants SET schema_server = 'localhost', schema_server_port = '3306', schema_username = 'mifos', schema_password = 'mifos' WHERE id=1;
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
You should be able to log into platform with Username: mifos and Password: password.
For client applications built on top of the platform see the https://github.com/keithwoodlock/mifosx-community-apps repository.
If you get the java.net.BindException: Address already in use :8080 exception whilst running the gradle command inside the mifosng-provider directory, you may need to kill the process which is already using 8080 (netstat -aon | grep 8080).