Installing Mifos

This file describes how to install Mifos for use in a production environment.

1. Software Requirements
   Before you can run Mifos, you will need to download and install
   the software packages below. Please see their respective web
   sites for details on how to install each package.

     * Sun Microsystems Java - JDK/JRE 1.6 (see Note)
     * MySQL - Community Edition 5.1.45
     * Jetty - 7.3

   Note: While most Mifos testing has been done using the JDK,
   only the JRE is needed to run Mifos.

2. Upgrading Mifos
   If you are upgrading Mifos from a previous release please refer to the pages
   referenced below.  For general upgrade procedures see:
   http://mifos.org/documentation/upgrades

   For upgrade instructions for this release see:
   http://mifosforge.jira.com/wiki/display/MIFOS/Mifos+2.2+Upgrade+Instructions

3. Configuring MySQL
    3.1. Setting Database Parameters
         Use the following configuration settings for MySQL. You can configure
         these settings using MySQL Administrator or by editing the my.ini file
         in your MySQL home directory.

         max_connections=300
         innodb_buffer_pool_size=1024M
         innodb_file_per_table
         log-error=mysql_error.log
         log-slow-queries=mysql_slow_query.log
         long_query_time=1

    3.2. Initializing the Mifos Database
         To initialize the Mifos database, run the commands below from the
         directory that contains this INSTALL file. These commands assume a
         schema named "mifos" has been created, with a username of "mifos" and a password of "mifos".
         Adjust them if your database login is different. See sections 6.1.4
         and 7.1 for more information.

         mysql -D mifos -u mifos -pmifos < db/sql/base-schema.sql
         mysql -D mifos -u mifos -pmifos < db/sql/base-data.sql
         mysql -D mifos -u mifos -pmifos < db/sql/init_mifos_password.sql

         If your database instance already has a "mifos" database, then
         you will need to drop the database before running the above commands.

4. Setting Java and Jetty Parameters
         Set the following environment variables:

         JAVA_HOME     ... directory where the JDK or JRE is installed
         JAVA          ... points directly to java binary
         JETTY_HOME    ... directory where Jetty is installed
         JAVA_OPTIONS  ... -Xms1024M -Xmx1024M -XX:MaxPermSize=256m

5. Installing the Mifos WAR
         Copy the mifos.war you downloaded to JETTY_HOME/webapps. If the
         following temporary directories exist, delete them:

         JETTY_HOME/webapps/mifos
         JETTY_HOME/work

6. Configuring and Running Mifos
    6.1. Configuring Mifos
         Because some settings in Mifos can only be changed from their default
         values once, before Mifos is run for the first time, you should review
         the default Mifos configuration. See section 7.1 for more information.

         6.1.1. Using the Default Configuration
                A default configuration is provided. If you want to quickly get
                Mifos up and running to try it out, then no configuration is
                needed.

         6.1.2. Using a Custom Configuration
                Create and set a new environment variable:

                MIFOS_CONF ... directory for Mifos custom configuration files

                (see http://mifos.org/documentation/configuration for further
                details and options).

         6.1.3. Changing the Default Mifos Configuration
                To make changes to the default configuration, copy the file
                config/applicationConfiguration.custom.properties to the
                MIFOS_CONF directory defined in 6.1.2.

         6.1.4. Changing the Default Database Connection Settings
                To use non-default settings for your database connection --
                such as a different port number, user name, or password -- copy
                the file config/local.properties to the MIFOS_CONF directory
                defined in 6.1.2.

    6.2. Running Mifos
         Execute the Jetty startup script in JETTY_HOME/bin, or if Jetty
         was installed as a service on Windows, navigate to Control Panel >
         Administrative Tools > Services to verify that the service's status
         is "Started".

         Next, visit the base URL in a browser:

         http://localhost:8080/mifos

         username: mifos
         password: testmifos

7. Mifos Documentation Links
   Use the following links for more information about Mifos.

    7.1. Configuring Mifos - http://mifos.org/documentation/configuration
         Pay particular attention to "trapdoor" settings (settings that can
         only be changed to a non-default value once) in the application
         configuration file. Chart of Accounts configuration is one such
         "trapdoor".

    7.2. Release Notes -
         http://mifosforge.jira.com/wiki/display/MIFOS/v2.2

    7.3. System Recommendations (hardware, networking) -
         http://mifosforge.jira.com/wiki/display/MIFOS/Mifos+System+Recommendations+v2.2

    7.4. Ubuntu Install Guide -
         http://mifosforge.jira.com/wiki/display/MIFOS/Ubuntu+Install
         This is an installation guide describing how to install Mifos by
         building it from the source code.

    7.5. Ubuntu Quick Install Guide -
         http://mifosforge.jira.com/wiki/display/MIFOS/Ubuntu+WAR+Install
         This is an installation guide for Ubuntu describing how to install
         Mifos from the WAR file, similar to this INSTALL file.

    7.6. Windows Install Guide -
         http://mifos.org/documentation/installation/windows-installation-guide
         This is an installation guide for Windows describing how to install
         Mifos from the WAR file, similar to this INSTALL file.

8. Third Party Licenses
   All software libraries used by Mifos are compatible with the Apache License
   2.0. To obtain a report detailing these licenses, execute "mvn site" in a
   local copy of the Mifos source code.