Mifos X Platform 24.04.30 - Installation Instructions on Linux Ubuntu 24.04 LTS

Objective

Provide clear instructions in order to Install the Mifos Platform 24.04.30 Release on a Linux Ubuntu 24.04 LTS Operating System, these instructions should ideally be executed by users with basic technical skills.

Target Audience

Username	User description
General Public	User should have basic knowledge about Linux commands.

System requirements

Hardware:

8Gb RAM
2 vCPUs (Intel x86 64bits or AMD x86 64bits)
32Gb Storage

Software:

Linux Ubuntu 24.04 LTS 64 bits Operating System
Apache Tomcat 10.1
Java JDK Zulu version 17 LTS
MariaDB 11.2

Deployment Architecture

This is a graphical representation of the components that will be installed, they are highlighted in yellow, and the others put in the graphic as a reference and they can be used for extending the functionality.

Instructions

*The following commands must be verified in a text plain editor before being executed.

Install Java Zulu JDK 17

sudo apt install gnupg ca-certificates curl

curl -s https://repos.azul.com/azul-repo.key | sudo gpg --dearmor -o /usr/share/keyrings/azul.gpg

echo "deb [signed-by=/usr/share/keyrings/azul.gpg] https://repos.azul.com/zulu/deb stable main" | sudo tee /etc/apt/sources.list.d/zulu.list

sudo apt update

sudo apt install zulu17-jdk

java -version

You should see something like below and if so the your java installation is successfull
openjdk version "17.0.12" 2024-07-16 LTS
OpenJDK Runtime Environment Zulu17.52+17-CA (build 17.0.12+7-LTS)
OpenJDK 64-Bit Server VM Zulu17.52+17-CA (build 17.0.12+7-LTS, mixed mode, sharing)

Get the Apache Tomcat version 10.1 which is the Application Server required to run Mifos X 23.12-RELEASE
PLEASE NOTE
The latest tomcat release will change and the link below may become invalid.
If wget fails, get the correct link by going to https://dlcdn.apache.org/tomcat/tomcat-10 for example at time of writing this, the available tomcat-10 is v10.1.30

wget https://dlcdn.apache.org/tomcat/tomcat-10/v10.1.30/bin/apache-tomcat-10.1.30.tar.gz

or if above link fails you can use the archives of tomcat-10 with the link below

Take the following steps on the downloaded file
1. untar it and delete the tar file
2. mv the file to /usr/share/tomcat10
3. delete the folders found int the webapps folder to be replaced by the files of MifosX
  the commands below will do the steps above

sudo wget https://dlcdn.apache.org/tomcat/tomcat-10/v10.1.30/bin/apache-tomcat-10.1.30.tar.gz &&
sudo tar -zxvf apache-tomcat-10.1.30.tar.gz &&
sudo rm -f apache-tomcat-10.1.30.tar.gz &&
sudo mv apache-tomcat-10.1.30 /usr/share/tomcat10 &&
sudo rm -r /usr/share/tomcat10/webapps/ROOT &&
sudo rm -r /usr/share/tomcat10/webapps/docs &&
sudo rm -r /usr/share/tomcat10/webapps/examples &&
sudo rm -r /usr/share/tomcat10/webapps/host-manager &&
sudo rm -r /usr/share/tomcat10/webapps/manager

Download the Mifos X 24.04.30 package

cd $HOME

wget https://sourceforge.net/projects/mifos/files/Mifos%20X/mifosplatform-24.04.30.RELEASE.zip

unzip mifosplatform-24.04.30.RELEASE.zip

Rename the WebApp folder to ROOT and Copy it to the tomcat10/webapps/ folder which will be used as the back office (UI)

mv mifosplatform-24.04.30.RELEASE/webapp/ mifosplatform-24.04.30.RELEASE/ROOT

sudo cp -r mmifosplatform-24.04.30.RELEASE/ROOT /usr/share/tomcat10/webapps/

Copy the Apache Fineract binary

sudo cp -r mifosplatform-24.04.30.RELEASE/fineract-provider.war /usr/share/tomcat10/webapps/

cd $HOME

Download the mariadb drive 3.3.2, copy the driver to the tomcat10/lib/ folder and Install MariaDB v11.2 Database server

sudo wget https://downloads.mariadb.com/Connectors/java/connector-java-3.3.2/mariadb-java-client-3.3.2.jar && sudo cp -r mariadb-java-client-3.3.2.jar /usr/share/tomcat10/lib

sudo apt install software-properties-common -y &&
curl -LsS -O https://downloads.mariadb.com/MariaDB/mariadb_repo_setup &&
sudo bash mariadb_repo_setup --mariadb-server-version=11.2

sudo apt update

sudo apt install mariadb-server mariadb-client -y

confirm your installation by running the command below

sudo systemctl status mariadb

Secure the installation setting a password for the root user

sudo mariadb-secure-installation

if you wish to change the ports and other configurations run

sudo nano /etc/mysql/mariadb.conf.d/50-server.cnf and restart the database server

sudo systemctl restart mariadb.service

Connect to MariaDB in order to create the two databases required by Apache Fineract

mariadb -uroot -p

CREATE database `fineract_tenants` ;

CREATE database `fineract_default` ;

exit

Export the environment variables required by Apache Fineract in order to use the root password that was set in the step “h”, also

MXD-121 - Getting issue details... STATUS

we are disabling the SSL because this is a demonstration. We encourage you to use the secure connection by enabling HTTPS.

export FINERACT_DEFAULT_TENANTDB_PWD=skdcnwauicn2ucnaecasdsajdnizucawencascdca

export FINERACT_HIKARI_PASSWORD=skdcnwauicn2ucnaecasdsajdnizucawencascdca

export FINERACT_SERVER_SSL_ENABLED=false

export FINERACT_SERVER_PORT=8080

Note: The username and password are shown as an example, you must enter your own username and password.

Run the command for executing the Apache Tomcat

./catalina.sh run

Open the Mifos X 24.04 User Interface on a web browser

http://localhost:8080

The credentials for login:

user: mifos

password: password

Enjoy and give us feedback.

TO USE HTTPS YOU WILL NEED TO : Obtain a domain validation certificate from a certificate authority like https://letsencrypt.org/
You will have to enable SSL as below
- export FINERACT_SERVER_SSL_ENABLED=true
  export FINERACT_SERVER_PORT=8443 or your chosen port

For example if your URL is subdomain.domain.com, edit the /usr/share/tomcat10/conf/server.xml file to read as below

<?xml version="1.0" encoding="UTF-8"?>

<Server port="8005" shutdown="SHUTDOWN">
  <Listener className="org.apache.catalina.startup.VersionLoggerListener" />
  <Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />
  <Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener" />
  <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" />
  <Listener className="org.apache.catalina.core.ThreadLocalLeakPreventionListener" />

  <GlobalNamingResources>
    <Resource name="UserDatabase" 
              auth="Container"
              type="org.apache.catalina.UserDatabase"
              description="User database that can be updated and saved"
              factory="org.apache.catalina.users.MemoryUserDatabaseFactory"
              pathname="conf/tomcat-users.xml" />

    <Resource type="javax.sql.DataSource"
              name="jdbc/fineract_tenants"
              factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
              driverClassName="org.mariadb.jdbc.Driver" 
              url="jdbc:mariadb://localhost:3306/fineract_tenants"
              username="root"
              password="skdcnwauicn2ucnaecasdsajdnizucawencascdca"
              initialSize="3"
              maxActive="10"
              maxIdle="6"
              minIdle="3"
              validationQuery="SELECT 1"
              testOnBorrow="true"
              testOnReturn="true"
              testWhileIdle="true"
              timeBetweenEvictionRunsMillis="30000"
              minEvictableIdleTimeMillis="60000"
              logAbandoned="true"
              suspectTimeout="60"/>          
  </GlobalNamingResources>

  <Service name="Catalina">


    <Connector 
            port="443" 
            protocol="org.apache.coyote.http11.Http11NioProtocol"
            maxThreads="200" 
            scheme="https"
            secure="true" 
            SSLEnabled="true"
        defaultSSLHostConfigName="subdomain.domain.com"
            clientAuth="false" 
            sslProtocol="TLS"
            URIEncoding="UTF-8"
            compression="force"
            acceptCount="100" 
            minSpareThreads="25" 
            maxSpareThreads="75"
            enableLookups="false" 
            disableUploadTimeout="true"
            maxHttpHeaderSize="8192"
            compressableMimeType="text/html,text/xml,text/plain,text/javascript,text/css">
            <SSLHostConfig
                        hostName="subdomain.domain.com"
                        protocols="+TLSv1,+TLSv1.1,+TLSv1.2">
                        <Certificate
                            certificateFile="/etc/letsencrypt/live/subdomain.domain.com/cert.pem"
                            certificateKeyFile="/etc/letsencrypt/live/subdomain.domain.com/privkey.pem"
                            certificateChainFile="/etc/letsencrypt/live/subdomain.domain.com/chain.pem"/>
            </SSLHostConfig>
    </Connector>


    <Connector port="8080" 
               protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8443"
               maxParameterCount="1000"
               />
    
    <Engine name="Catalina" defaultHost="localhost">

      <Realm className="org.apache.catalina.realm.LockOutRealm">
        <Realm className="org.apache.catalina.realm.UserDatabaseRealm" resourceName="UserDatabase"/>
      </Realm>

      <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" />

      </Host>
    </Engine>
  </Service>
</Server>

<?xml version="1.0" encoding="UTF-8"?>

<Server port="8005" shutdown="SHUTDOWN">
  <Listener className="org.apache.catalina.startup.VersionLoggerListener" />
  <Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />
  <Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener" />
  <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" />
  <Listener className="org.apache.catalina.core.ThreadLocalLeakPreventionListener" />

  <GlobalNamingResources>
    <Resource name="UserDatabase" 
              auth="Container"
              type="org.apache.catalina.UserDatabase"
              description="User database that can be updated and saved"
              factory="org.apache.catalina.users.MemoryUserDatabaseFactory"
              pathname="conf/tomcat-users.xml" />

    <Resource type="javax.sql.DataSource"
              name="jdbc/fineract_tenants"
              factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
              driverClassName="org.mariadb.jdbc.Driver" 
              url="jdbc:mariadb://localhost:3306/fineract_tenants"
              username="root"
              password="skdcnwauicn2ucnaecasdsajdnizucawencascdca"
              initialSize="3"
              maxActive="10"
              maxIdle="6"
              minIdle="3"
              validationQuery="SELECT 1"
              testOnBorrow="true"
              testOnReturn="true"
              testWhileIdle="true"
              timeBetweenEvictionRunsMillis="30000"
              minEvictableIdleTimeMillis="60000"
              logAbandoned="true"
              suspectTimeout="60"/>          
  </GlobalNamingResources>

  <Service name="Catalina">


    <Connector 
            port="443" 
            protocol="org.apache.coyote.http11.Http11NioProtocol"
            maxThreads="200" 
            scheme="https"
            secure="true" 
            SSLEnabled="true"
        defaultSSLHostConfigName="subdomain.domain.com"
            clientAuth="false" 
            sslProtocol="TLS"
            URIEncoding="UTF-8"
            compression="force"
            acceptCount="100" 
            minSpareThreads="25" 
            maxSpareThreads="75"
            enableLookups="false" 
            disableUploadTimeout="true"
            maxHttpHeaderSize="8192"
            compressableMimeType="text/html,text/xml,text/plain,text/javascript,text/css">
            <SSLHostConfig
                        hostName="subdomain.domain.com"
                        protocols="+TLSv1,+TLSv1.1,+TLSv1.2">
                        <Certificate
                            certificateFile="/etc/letsencrypt/live/subdomain.domain.com/cert.pem"
                            certificateKeyFile="/etc/letsencrypt/live/subdomain.domain.com/privkey.pem"
                            certificateChainFile="/etc/letsencrypt/live/subdomain.domain.com/chain.pem"/>
            </SSLHostConfig>
    </Connector>


    <Connector port="8080" 
               protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8443"
               maxParameterCount="1000"
               />
    
    <Engine name="Catalina" defaultHost="localhost">

      <Realm className="org.apache.catalina.realm.LockOutRealm">
        <Realm className="org.apache.catalina.realm.UserDatabaseRealm" resourceName="UserDatabase"/>
      </Realm>

      <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" />

      </Host>
    </Engine>
  </Service>
</Server>

Create the /usr/share/tomcat10/bin/setenv.sh file in which you can edit parameters like passwords and others using the command
sudo nano /usr/share/tomcat10/bin/setenv.sh edit the file to look as show below

export FINERACT_NODE_ID="1"

export FINERACT_HIKARI_DRIVER_SOURCE_CLASS_NAME="org.mariadb.jdbc.Driver"
export FINERACT_HIKARI_JDBC_URL="jdbc:mariadb://localhost:3306/fineract_tenants"
export FINERACT_HIKARI_USERNAME="root"
export FINERACT_HIKARI_PASSWORD="skdcnwauicn2ucnaecasdsajdnizucawencascdca"

export FINERACT_HIKARI_MINIMUM_IDLE="3"
export FINERACT_HIKARI_MAXIMUM_POOL_SIZE="10"
export FINERACT_HIKARI_IDLE_TIMEOUT="60000"
export FINERACT_HIKARI_CONNECTION_TIMEOUT="20000"
export FINERACT_HIKARI_TEST_QUERY="SELECT 1"
export FINERACT_HIKARI_AUTO_COMMIT="true"
export FINERACT_HIKARI_DS_PROPERTIES_CACHE_PREP_STMTS="true"
export FINERACT_HIKARI_DS_PROPERTIES_PREP_STMT_CACHE_SIZE="250"
export FINERACT_HIKARI_DS_PROPERTIES_PREP_STMT_CACHE_SQL_LIMIT="2048"
export FINERACT_HIKARI_DS_PROPERTIES_USE_SERVER_PREP_STMTS="true"
export FINERACT_HIKARI_DS_PROPERTIES_USE_LOCAL_SESSION_STATE="true"
export FINERACT_HIKARI_DS_PROPERTIES_REWRITE_BATCHED_STATEMENTS="true"
export FINERACT_HIKARI_DS_PROPERTIES_CACHE_RESULT_SET_METADATA="true"
export FINERACT_HIKARI_DS_PROPERTIES_CACHE_SERVER_CONFIGURATION="true"
export FINERACT_HIKARI_DS_PROPERTIES_ELIDE_SET_AUTO_COMMITS="true"
export FINERACT_HIKARI_DS_PROPERTIES_MAINTAIN_TIME_STATS="false"
export FINERACT_HIKARI_DS_PROPERTIES_LOG_SLOW_QUERIES="true"
export FINERACT_HIKARI_DS_PROPERTIES_DUMP_QUERIES_IN_EXCEPTION="true"

export FINERACT_DEFAULT_TENANTDB_HOSTNAME="localhost"
export FINERACT_DEFAULT_TENANTDB_PORT="3306"
export FINERACT_DEFAULT_TENANTDB_UID="root"
export FINERACT_DEFAULT_TENANTDB_PWD="skdcnwauicn2ucnaecasdsajdnizucawencascdca"
export FINERACT_DEFAULT_TENANTDB_CONN_PARAMS=""
export FINERACT_DEFAULT_TENANTDB_TIMEZONE="Africa/Freetown"
export FINERACT_DEFAULT_TENANTDB_IDENTIFIER="default"
export FINERACT_DEFAULT_TENANTDB_NAME="fineract_default"
export FINERACT_DEFAULT_TENANTDB_DESCRIPTION="Default Demo Tenant"

export FINERACT_NODE_ID="1"

export FINERACT_HIKARI_DRIVER_SOURCE_CLASS_NAME="org.mariadb.jdbc.Driver"
export FINERACT_HIKARI_JDBC_URL="jdbc:mariadb://localhost:3306/fineract_tenants"
export FINERACT_HIKARI_USERNAME="root"
export FINERACT_HIKARI_PASSWORD="skdcnwauicn2ucnaecasdsajdnizucawencascdca"

export FINERACT_HIKARI_MINIMUM_IDLE="3"
export FINERACT_HIKARI_MAXIMUM_POOL_SIZE="10"
export FINERACT_HIKARI_IDLE_TIMEOUT="60000"
export FINERACT_HIKARI_CONNECTION_TIMEOUT="20000"
export FINERACT_HIKARI_TEST_QUERY="SELECT 1"
export FINERACT_HIKARI_AUTO_COMMIT="true"
export FINERACT_HIKARI_DS_PROPERTIES_CACHE_PREP_STMTS="true"
export FINERACT_HIKARI_DS_PROPERTIES_PREP_STMT_CACHE_SIZE="250"
export FINERACT_HIKARI_DS_PROPERTIES_PREP_STMT_CACHE_SQL_LIMIT="2048"
export FINERACT_HIKARI_DS_PROPERTIES_USE_SERVER_PREP_STMTS="true"
export FINERACT_HIKARI_DS_PROPERTIES_USE_LOCAL_SESSION_STATE="true"
export FINERACT_HIKARI_DS_PROPERTIES_REWRITE_BATCHED_STATEMENTS="true"
export FINERACT_HIKARI_DS_PROPERTIES_CACHE_RESULT_SET_METADATA="true"
export FINERACT_HIKARI_DS_PROPERTIES_CACHE_SERVER_CONFIGURATION="true"
export FINERACT_HIKARI_DS_PROPERTIES_ELIDE_SET_AUTO_COMMITS="true"
export FINERACT_HIKARI_DS_PROPERTIES_MAINTAIN_TIME_STATS="false"
export FINERACT_HIKARI_DS_PROPERTIES_LOG_SLOW_QUERIES="true"
export FINERACT_HIKARI_DS_PROPERTIES_DUMP_QUERIES_IN_EXCEPTION="true"

export FINERACT_DEFAULT_TENANTDB_HOSTNAME="localhost"
export FINERACT_DEFAULT_TENANTDB_PORT="3306"
export FINERACT_DEFAULT_TENANTDB_UID="root"
export FINERACT_DEFAULT_TENANTDB_PWD="skdcnwauicn2ucnaecasdsajdnizucawencascdca"
export FINERACT_DEFAULT_TENANTDB_CONN_PARAMS=""
export FINERACT_DEFAULT_TENANTDB_TIMEZONE="Africa/Freetown"
export FINERACT_DEFAULT_TENANTDB_IDENTIFIER="default"
export FINERACT_DEFAULT_TENANTDB_NAME="fineract_default"
export FINERACT_DEFAULT_TENANTDB_DESCRIPTION="Default Demo Tenant"

If you require some help please contact us. These are the channels available to get in contact: https://mifos.org/resources/community/communications/

Please include screens, logs (use a paste tool like https://privatebin.net/ ), description of the issue with all the details that you can share. Please be careful and avoid to include sensitive data.

Remember that these installation instructions are for a quick way to get the Mifos X Platform up and running very quickly. You have to protect the sensitive data in motion/rest, secrets, connections, credentials, etc. based on your local requirements.