Mifos X Installation on Linux - Ubuntu Server

Mifos X Ubuntu Server 16.04 Installation Guide:

Linux Server for Fineract Platform using Ubuntu Server 16.04,

Java-JDK (v.1.8.0_231 & above),

Tomcat server (v. & above) 

MYSQL server (v5.5 or v5.6  not above or below).  and not recommended to use any other version in live production outside of what is provided here

Step 1 - Installing System Updates and Prerequisites:

Run all below mentioned scripts one by one on the ubuntu console & follow step by step instructions: - 

# sudo apt-get update

# sudo apt-get upgrade

# sudo apt-get install python-software-properties 

# sudo apt-get install software-properties-common

# sudo add-apt-repository ppa:webupd8team/java 

# sudo apt-get update 

 Install Java : 

sudo apt-get install oracle-java8-installer

# sudo -E add-apt-repository ppa:openjdk-r/ppa
# sudo apt-get update
# sudo apt-get install openjdk-8-jdk

java license agreement

On prompting for accepting oracle java agreement, accept the agreement by pressing y(yes) key.

On completion of java installation,one could verify the installed version by & should be 1.8v:-
# java -version 

Install mysql-server : 

# sudo apt-get install mysql-server 

mysql password

set mysql root password to: mysql

(Bad for security, but just to get all installed and instructions on how to change it will be provided later in this guide)

  • You could skip to Appendix A below and setup a custom mifos db user/password right away.
On completion of java installation,one could verify the installed version by & should be 5.5v:-
# mysql --version

Install tomact : 


The latest tomcat release will change and the link below may become invalid. If wget fails, get the correct link by going to https://tomcat.apache.org/download-70.cgi and under the core section, selecting the link to the tar.gz file. Use it for wget below:-

# sudo wget http://archive.apache.org/dist/tomcat/tomcat-7/v7.0.85/bin/apache-tomcat-7.0.85.tar.gz

 # sudo mv apache-tomcat-7.0.109.tar.gz /usr/share

 # cd /usr/share 

 # sudo tar xvf apache-tomcat-7.0.109.tar.gz

 # sudo rm -f apache-tomcat-7.0.109.tar.gz

 # sudo mv apache-tomcat-7.0.85 tomcat7

Install nano - text editor 

# sudo apt-get install nano

OPTIONAL (date/time settings) 

Check date:

# date

and if needed update with

# dpkg-reconfigure tzdata 

Step 2 - Tomcat setup

Enabling SSL

To enable tomcat SSL (https), generate and store a key:

# sudo keytool -genkey -keyalg RSA -alias tomcat -keystore /usr/share/tomcat.keystore

set keystore password

set password to: xyz123

(Bad for security, but just to get all installed and instructions on how to change it will be provided later in this guide)

This gets stored in /usr/share as tomcat.keystore

Updating server.xml configuration file

It is located at /usr/share/tomcat7/conf/server.xml path

# sudo nano /usr/share/tomcat7/conf/server.xml 

nano shortcut keys

Tip: To delete line by line you could use ctrl+k
To exit you could use ctrl+x
To confirm say yes & you could use y
then click on enter button to save

copy and replace below content into it

<?xml version='1.0' encoding='utf-8'?>
<Server port="8005" shutdown="SHUTDOWN">
<Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />
<Listener className="org.apache.catalina.core.JasperListener" />
<Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener" />
<Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" />
<Listener className="org.apache.catalina.core.ThreadLocalLeakPreventionListener" />

<Resource name="UserDatabase" auth="Container"
description="User database that can be updated and saved"
pathname="conf/tomcat-users.xml" />

<Resource type="javax.sql.DataSource"
validationQuery="SELECT 1"

<Service name="Catalina"> 
<Connector protocol="org.apache.coyote.http11.Http11Protocol"
port="443" maxThreads="200" scheme="https"
secure="true" SSLEnabled="true"
clientAuth="false" sslProtocol="TLS"

<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />

<Engine name="Catalina" defaultHost="localhost">

<Realm className="org.apache.catalina.realm.LockOutRealm">

<Realm className="org.apache.catalina.realm.UserDatabaseRealm"

<Host name="localhost" appBase="webapps"
unpackWARs="true" autoDeploy="true">
<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
prefix="localhost_access_log." suffix=".txt"
pattern="%h %l %u %t &quot;%r&quot; %s %b" />



If your any of the server port connections are using port number = 443, then you need to change your port number to 8443, in server.xml here:-

port="443" maxThreads="200" scheme="https" to port="8443" maxThreads="200" scheme="https" 

Download drizzle jdbc connector

Place it under lib folder 

# cd /usr/share/tomcat7/lib

# sudo wget https://repo1.maven.org/maven2/org/drizzle/jdbc/drizzle-jdbc/1.3/drizzle-jdbc-1.3.jar

Download mysql jdbc connector

Download it from https://dev.mysql.com/downloads/connector/j/,

# wget https://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-j_8.0.31-1ubuntu18.04_all.deb

Then unzip it

#tar -xvf mysql-connector-java-5.1.49.tar.gz

#rm -r mysql-connector-java-5.1.49.tar.gz

Then place the .jar in the  /usr/share/tomcat7/lib  folder. 

#sudo mv mysql-connector-java-5.1.49/mysql-connector-java-5.1.49-bin.jar /usr/share/tomcat7/lib/

#sudo mv mysql-connector-java-5.1.49/mysql-connector-java-5.1.49.jar /usr/share/tomcat7/lib/

#rm -r mysql-connector-java-5.1.49

The filename above will vary depending on what the latest version of the connector is

Edit /etc/init.d/tomcat7

# sudo nano /etc/init.d/tomcat7

copy below red colored content into it & exit by pressing ctrl+x then confirm with y for yes. 

# Provides:         tomcat
# Required-Start:    $all
# Required-Stop:
# Default-Start:     2 3 4 5
# Default-Stop:
# Short-Description: Auto-starts tomcat
# pidfile: /var/run/tomcat.pid

case $1 in
sh /usr/share/tomcat9/bin/startup.sh
sh /usr/share/tomcat9/bin/shutdown.sh
sh /usr/share/tomcat9/bin/shutdown.sh
sh /usr/share/tomcat9/bin/startup.sh
exit 0
Then Execute on Terminal the command below

# sudo chmod 755 /etc/init.d/tomcat7

Link this script to the startup folders with a symbolic link.Execute these two commands.

# sudo ln -s /etc/init.d/tomcat7 /etc/rc1.d/K99tomcat
# sudo ln -s /etc/init.d/tomcat7 /etc/rc2.d/S99tomcat

Step 3 - Fineract Platform and Database Setup/Population

Download and extract Fineract platform:

For latest release you can download from or If wget/download fails, this link:- http://sourceforge.net/projects/mifos/files/Mifos%20X/ )

# cd /usr/src

# sudo wget https://jaist.dl.sourceforge.net/project/mifos/Mifos%20X/mifosplatform-18.03.01.RELEASE.zip

# sudo unzip mifosplatform-18.03.01.RELEASE.zip

# cd fineractplatform-18.03.01.RELEASE

Initialize MySQL data 

# mysql -u root -p

Enter mysql root password, and in mysql console type: 

create database `mifosplatform-tenants`;
create database `mifostenant-default`;

# mysql -u root -pmysql mifosplatform-tenants < database/mifospltaform-tenants-first-time-install.sql 

Optional - If you want to load sample data, otherwise you could skip this par: 

# mysql -u root -p mifostenant-default < database/migrations/sample_data/load_sample_data.sql

Step 4 - Activate Mifos

Copy fineract-platform and community app into Tomcat's webapps folder: 

# cd /usr/src/fineractplatform-18.03.01.RELEASE

# sudo cp fineract-provider.war /usr/share/tomcat7/webapps/

# sudo cp -r apps/community-app/ /usr/share/tomcat7/webapps/ 

# sudo cp -r api-docs/ /usr/share/tomcat7/webapps/

# cd /usr/share/tomcat7/webapps

# sudo mv ROOT OLDROOT

# sudo mv community-app ROOT

Create a directory for reports (pentahoReports):

# sudo -i 

# cd /root 

# mkdir .mifosx

# cp -r /usr/src/fineractplatform-18.03.01.RELEASE/pentahoReports /root/.mifosx 

pentahoReports & upload directory

Pentaho Reports

If /pentahoReports  is not copied into /root/.mifosx, penatoh reports,ex:accounting reports will fail with:

Income Statement.prpt","defaultUserMessage":"Unable to create key: No loader was able to handle the given key data: /usr/share/tomcat7/.mifosx/pentahoReports/Income Statement.prpt","userMessageGlobalisationCode":"error.msg.reporting.error","parameterName":null,"value"

Upload Directory

  • .fineract directory gets created automatically, if not created then Clients > Upload Documents  will fail with:  "Error error.msg.document.save"  (firebug, network tab)
  • Access to this directory should be restricted to authorized personnel only.
    While all accounting related information is stored in a database, submitted documents are simply stored in orginal format as uploaded. Mifos will store user uploaded files/documents relating to clients,loans,etc   in .fineract/

and finally to start

sudo /etc/init.d/tomcat7 start

Setup is complete and mifos should be running. 

In case if it throws error ClassNotFoundException org.apache.catalina.core.JasperListener you need to remove the below line from server.xml 

<Listener className="org.apache.catalina.core.JasperListener" /> 

*in separate terminal you may watch your Mifos(logs) come to life like this: 

tail -f /usr/share/tomcat7/logs/catalina.out 

(if all is good, after a while of loading, you should see something like: Root WebApplicationContext: initialization completed in 45876 ms)

It's Done!


You could access Mifos X through any internet browser:- 

@ https://server ip address 

or if you are using server port number as 8443 then you could access it https://localhost:8443

With these credentials:-

username: mifos

password: password

Additional info:-

  • Platform application should be available @ https://[public DNS]/fineract-provider/api/v1/offices?tenantIdentifier=default&pretty=true
  • API docs should be available @ https://[public DNS]/api-docs/apiLive.htm

Optional title - Appendix A

Appendix A - To change mysql username/password

Change Mifos default mysql password:

# apt-get install phpmyadmin

1.  Go to   http://[yourserverip]/phpmyadmin  and login

2.  Click on Privileges, then Add a new User

3. Pick a username/password and create it. Assign full privileges globally, or on  mifosplatform-tenants &  mifostenant-default databases.

4. On the left, select/open mifosplatform-tenants database,
you should see a table with a single column , click "edit" infront of it.


And set user/pass created in step #3.

Finally, edit


And set user/pass created in step #3 here as well.

You can now set new mysql root password, without braking mifos.

Restart tomcat. Finish.

sudo /etc/init.d/tomcat7 restart

Need Help?

If you need help on the Mifos Installation, you could always reach our partners:-


Ex: https://mifos.org/directory/listing/intelligrow-consultancy-services-private-limited/

Welcome to Mifos community, If you are stuck with the Mifos Installation or need training or customization or need any help with respect to mifos please reach to us at:

Sangamesh Nadagoudar,
sangamesh@intelligrow.co or info@intelligrow.co or sangameshintelligrow@gmail.com



We would be happy to help you.