Mifos X Platform 25.03.22 - Installation Instructions on Linux Ubuntu 24.04 LTS -MariaDB and 2FA

Username

User description

General Public

Users should have basic knowledge about Linux commands.

Hardware:

• 8Gb RAM 

• 2 vCPUs (Intel x86 64bits or AMD x86 64bits)

• 32Gb Storage 

Software:

• Linux Ubuntu 22.04 LTS 64 bits Operating System

• Apache Tomcat 10.1

• Java JDK Zulu version 17 LTS

• MariaDB 11.4

• Apache Fineract 1.11

1. Install Java Zulu JDK 17

Installation of the necessary tools:

$ sudo apt install gnupg ca-certificates curl

Download and convert the GPG key:

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

Add a new APT repository to install Azul Zulu packages:

$ 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

Update the package list:

$ sudo apt update

Install the Zulu JDK 17:

$ sudo apt install zulu17-jdk

Comprobar la versión de java:

$ java -version

2. Get the Apache Tomcat and Mifos X 25.03.22-RELEASE

Install apache Tomcat version 10.1.23 which is the Application Server required to run Mifos X 25.03.22-RELEASE:

$ wget https://dlcdn.apache.org/tomcat/tomcat-10/v10.1.34/bin/apache-tomcat-10.1.34.zip 

Unzip the file in a folder:

$ unzip apache-tomcat-10.1.34.zip

Delete the ROOT default content:

$ rm -Rf ./apache-tomcat-10.1.34/webapps/ROOT/*

Download the Mifos X 25.03.22 package:

$ cd $HOME

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

$ unzip mifosplatform-25.03.22.RELEASE.zip

$ cd mifosplatform-25.03.22.RELEASE

Open



Copy the Mifos WebApp which will be used as the backoffice 

$ cp -Rf ./webapp/* ../apache-tomcat-10.1.34/webapps/ROOT

Copy the Apache Fineract binary

$ cp fineract-provider.war ../apache-tomcat-10.1.34/webapps/

3. install MariaDB Database server

$ sudo apt update

$ sudo apt install mariadb-server

Secure the installation setting a password for the root user:

$ sudo mysql_secure_installation

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

$ mysql -u root -p 

$ CREATE database `fineract_tenants` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

$ CREATE database `fineract_default` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

$ exit

Export the environment variables required by Apache Fineract in order to use the root password that was set in the step “h”, also 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 25.03 User Interface on a web browser

http://localhost:8080

The credentials for login:

user: mifos 

password: password

1. Set up Apache Fineract's email service

Once inside the system: 

• Click the "Admin" button located at the top of the screen.

• Select the ‘System’ option.

Click the "External Services" option.

Select the "Email External Service" option.

Setup the  Apache Fineract's Email service for sending emails.

2. Ensure that users can receive emails

• Click the "Admin" button located at the top of the screen.

• Select the ‘Users’ option.

Select the user to configure (the admin user for this manual).

Edit the user to add a valid email address.

3. Set the environment variable in the docker-compose.yml file

Enter the mariadb folder

Once in the path, run the command:

$ vi docker-compose.yml

Press "i" to enter insert mode before the cursor.

At the end of the file, add the line:

• FINERACT_SECURITY_2FA_ENABLED=true

Press "Esc" to exit insert mode. To save changes and exit, type ‘:wq’ and press “Enter”.

Once in the path, we raise the docker compose containers with the command:

$ docker compose pull && docker compose down && docker compose up -d && docker compose logs -f

Validate that containers are lifted correctly:

4. Validate the use of Two-Factor Authentication (2FA) for login

Validate that Mifos X Release 25.03 uses 2FA. Enter the URL http://localhost in a web browser.

Sign in with the default credentials:

User: mifos

Password: password

Select the delivery method "Send email to {user}".

Click the "Request OTP" button.

The system will send the access token to the email provided in the previous steps.

In the OTP field, enter the token received by email.

Press the "Validate OTP" button.

The system should display a successful login.

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.

Enjoy and give us feedback.

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.