Product
 
Home > Developers > Build Mifos from Source > Windows Install Guide
Document Actions

Windows Install Guide

Notes for getting Mifos installed for developers and testers.  For best results, also consult the Mifos README

The instructions below tell you how to get the latest source code under development.  This code is not guaranteed to be stable.  If you need to install Mifos for test, you may want to use the demonstration or test servers.

If you are interested in learning what the full deployment process is for a microfinance organization, see our Knowledge Center.

Building and Installing Mifos

Please see README in the code source repository for additional information on software pre-requisites and installation instructions. These notes are supplemental.

These instructions are designed for developers, but they may be clear enough for anyone to try setting up Mifos on a machine. A page is forthcoming that describes how to install Mifos without building from source code.

Building Mifos

Building Mifos requires that you get the source code and set up several additional programs.

You will need the following packages to build and install:
      - Java 2 Standard Edition Development Kit (JDK) 5.0 version 1.5.0_X
      - My SQL Version 5.0
      - Tomcat 6
      - Apache Ant 1.7.0 or later

Running Mifos

This page has instruction for installing and running Mifos based on the same tools used to build Mifos.  If you just want to see Mifos working, try the Test Server or Demo Server.

Steps to Build and Install Mifos

If you wish to build Mifos from source code, follow these steps.
  1. Get the source code
  2. Download and install Java SDK
  3. Install Build software: Ant
  4. Install web server and databse software: Tomcat and MySQL
  5. Set Up Environment Variables
  6. Build the Application
  7. Run the Application

 Download and Install the Required Software

To build and run Mifos, you must install:

 - a Java SDK
 - MySQL
 - An application server - Tomcat
 - Apache Ant

 Some code branches may require additional downloads.  Consult the README for that code branch.

Install Java SDK

Get the Java SDK installed. This step is needed for both running Mifos– JBoss depends on Java- and for the build process.

  1. Before you do install a Java SDK, check to see if you have any previous versions of Java installed and uninstall them (unless you need them for something else)–-either the JVM (Java Virtual Machine) or the JDK (Developers Kit).
  2. If you you have Java installed and you don’t need that particular version, it is recommended that you uninstall it via Start menu->Control Panel->Add/Remove Programs. (ex: I had to remove java 1.4.2.)
  3. Download the Java SE JDK installer (JDK 5.0 Update X).
    • Keep in mind that newer release *could* cause changes, so be mindful if something is very new.
    • .war files built with later versions of Java won't work on later versions
  4. Install the Java 2 Standard Edition Development Kit (JDK) 5.0 version 1.5.0_X.
    • We recommend using all default options during the install.

Install Tomcat Application Server

Instructions for Apache Tomcat [NEEDS UPDATING!] 

Install MySQL 

Download  mySQL 5.0 

  1. Download mySQL 5.0
  2. Run MySQL setup.exe (Settings during wizard.
  3. Click Next> Detailed config select
  4. Click Next> keep the selection Developer Machine 
  5. Click Next> Multifunctional DB keep 
  6. Click Next> InnoDB Tablespace settings c: Installation Path> keep 
  7. Click DSS/OLAP keep
  8.  Click Enable TCP/IP Networking keep Port # keep
  9. Click Best support for Multilingualism – select
  10. Run the Instance Config Wizard to set up your DB password.

* Make certain you note what you set for your admin user/password *

**If you need to go back and check or reconfigure these settings, use the MySQL Server Instance Config Wizard, accessible via the Start menu under MySQL Administrator 5.0.

Optional:  Install MySQL 5.0 GUI Tools

You may find the MySQL 5.0 GUI tools

to be helpful.  You can still use MySQL4.x for your actual databases AND use MySQL 5.0 Administrator, Query Browser, and other  tools.

Install Build Software: Ant

Ant is used to build .war files from source and to build the database, if required.

  • This step is only necessary if you want to build Mifos from source code. Ant is not necessary to run Mifos.
  • You can download Ant from apache.org. Install them by unpacking/unzipping and copy to a directory.
  • You may put Ant wherever you like, though examples may feature it under C:\
  • No other installation required.

In a section below, you will be instructed on how to set up your Environment Variables to get Ant to function.

Set Environment Variables

Setting Path and Creating Environment Variables in Windows

Use this setup if you plan to work from a Windows command prompt. You can also create a .bat file to set the path and the environment variables and run it each time prior to building and/or running Mifos. You need only follow steps 1-3 once.

1) Add directories to the System Path

  1. Go to Windows Start Menu
  2. Right-click My Computer
  3. Select Properties
  4. Select Advanced Tab
  5. Click Environment Variables
  6. Under System Variables, scroll down to Path
  7. Semicolons separate the Path entries. Append a semicolon to the existing path and add the paths to the bin directories of your Java SDK, Ant, and Tomcat, as shown in the example below. (Note that the paths may differ on your machine, depending upon where you installed the applications.)

Ex: C:\Program Files\Java\jdk1.5.0_12\bin;C:\apache-ant-1.7.0\bin;C:\apache-tomcat-6.0.14\bin

2) Add Required Environment Variables
Three environment variables must be set:

  • JAVA_HOME should be set to your Java SDK directory (ex: C:\Program Files\Java\jdk1.5.0_12)
  • ANT_HOME should be set to your Ant directory, (ex: C:\apache-ant-1.7.0) 
  • CATALINA_HOME should be set to your Tomcat directory (ex: C:\Program Files\Apache Software Foundation\Tomcat 6.0)
To Set up an Environment Variable in Windows XP:
  1. Go to Windows Start Menu
  2. Right-click My Computer
  3. Select Properties
  4. Select Advanced Tab
  5. Click Environment variables
  6. Under System Variables, click New
  7. Enter the Variable name (ex. JAVA_HOME)
  8. Enter the Variable value (ex. C:\Program Files\Java\jdk1.5.0_12)
  9. Click OK
  10. Repeat for all variables listed above

 

3) Verify Path and Environment Variables

  1. Open a new command prompt
  2. run echo %Path% and make sure the path looks correct (including semi-colons). Notice that MySQL is also in the Path:

    C:\Documents and Settings\auser>echo %Path%
    output:
    C:\WINDOWS\system32;C:\WINDOWS;C:\WINDOWS\System32\Wbem;C:\Program Files\QuickT
    me\QTSystem\;C:\Program Files\MySQL\MySQL Server 5.0\bin;C:\Program Files\Java\
    dk1.5.0_12\bin;C:\apache-ant-1.7.0\bin;c:\apache-tomcat-6.0.14\bin

c. run echo %[ENVIRONMENT VARIABLE]% for each environment variable and make certain each one is correct:


C:\Documents and Settings\auser>echo %JAVA_HOME%

C:\Program Files\Java\jdk1.5.0_12

C:\Documents and Settings\auser>echo %ANT_HOME%

C:\apache-ant-1.7.0

C:\Documents and Settings\auser>echo %CATALINA_HOME%

C:\Program Files\Apache Software Foundation\Tomcat 6.0

 

Build the Application

If you have not yet consulted the README with the source code, now is a good time to open it and review, as the steps may be more detailed.

1) Prepare your .properties Files

In .\trunk\mifos\conf, make changes to build.properties and hibernate.properties for the mySQL access. You need to change the passwords to whatever you set up on MySQL.

 
db.user=[user name for MySQL]
db.pwd=[password for MySQL]

** Change the values shown above to the login credentials for the account you created when you set up the Mifos db in mySQL.

2) Build Mifos using Ant

  ( running ant -p shows the targets available.  REview build.xml if you are familiar with ant and wish to change targets)

  1. Execute the following command from [local mifos src directory]\trunk\mifos:
    • ant clean compile copy_files war or  ant clean; ant compile; ant copy_files; ant war  
    • This process currently takes a few minutes to run.
  2. The .war file will be in ..\trunk\mifos\dist

 To only build the database:

From ..\trunk\mifos, run ant build_db

Note that is a database does not exist, a db will be created automatically during the startup.

Run the Application

1) Verify MySQL Services Are Running

Start up MySQL server either using the MySQL System Tray utility or by following the instructions below.

  1. Go to Control Panel-->Administrative Tools-->Services
  2. Scroll to MySQL.
  3. If the service is not running, start it.


2) Configure the Tomcat Installation with mifos.war

[This section was blank so I'm adding my humble experience, please edit to your heart's desire with any improvements. - Bart, bberning]

  1. Download tomcat (check mifos.org for current version, today it's 6.0)
  2. Run the default installation.
  3. Copy mifos.war into /webapps/ directory.
  4. Add environment variables.
    Go to Control Panel->System->Advanced Tab, click Environment Variables. Enter:
    Variable name: CATALINA_HOME
    Variable value: <depends on your path, mine is C:\MifosInstances\tip\Tomcat60>

    Variable name: Path
    Variable value: <add this to the end>;C:\MifosInstances\tip\Tomcat60\bin
  5. Check that tomcat is running - go  to  http://localhost:8080/manager/html.  The webpage shows what applications are running.
  6. Go to http://localhost:8080/docs for some marginally useful documentation.

Changing Memory Settings

Some reports were causing an out of memory error, so to change the Java Options, do the following.
  1. Programs-> Apache Tomcat 6.0 -> Configure Tomcat which launches a small app called 'Apache Tomcat Properties'.
  2. Go to the Java tab.
  3. Add these two rows in the window called 'Java Options'.
    -XX:PermSize=64m
    -XX:MaxPermSize=256m
  4. Additionally, on the same tab, you can also change the 'Initial memory pool' to 64MB and the 'Maximum memory pool' to 256MB.
  5. Search mifos.org for PermGen for more help on memory issues.

Running NOT as a automatic Windows Service

  1. I don't run Apache as a service always, so I went to Control Panel -> Services to change the Startup Type to 'Manual'. 
  2. Use the first screen in the 'Apache Tomcat Properties' app (see above) to start and stop tomcat.
  3. You can also start it as a Service from the Command Prompt with 'net start Tomcat6'.

 

3) Run the Application

    <this section needs to be updated>

    4) Use Mifos

    In a browser open:

    http://localhost:8080/mifos

    Username: mifos

    Password: testmifos

    If you are able to log into Mifos, you have correctly installed the application.  If you are not able to see the login page, you need to start troubleshooting.

     

    last modified 2008-07-24 01:28
    Grameen logo