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

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.12 package:

$ cd $HOME

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

$ unzip mifosplatform-25.12.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 previous step, 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. Start Keycloak with Docker.

Run the command:

docker run -p 9090:9090 -e KC_HTTP_PORT=9090 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin http://quay.io/keycloak/keycloak:26.0.7 start-dev

Access the URL from a web browser:

http://localhost:9090/

Open

docker run -p {$host_port}:{$container_port} -e KC_HTTP_PORT={$container_port} -e KC_BOOTSTRAP_ADMIN_USERNAME={$admin_user} -e KC_BOOTSTRAP_ADMIN_PASSWORD={$admin_password} http://quay.io/keycloak/keycloak:{$version} start-dev

The username and password were defined in the command executed in the previous step.

2. Create a tenant in Keycloak.

It is necessary to create a tenant:

• Click the dropdown menu located at the top of the left sidebar.

• Press the "Create realm" button.

• Assign a name to the tenant (webapp for this manual).

• Mark the "Enabled" option as 'On'.

• Press the "Create" button.

3. Create and configure a user in Keycloak.

To create a user:

• Select the "Users" section from the left sidebar.

• Press the "Create new user" button in the center of the screen.

Enter the requested values:  

Username: mifos  

Email: {$valid_email}  

First name: {$first_name}  

Last name: {$last_name}  

Press the "Create" button at the bottom of the window.

Note: Replace the values within curly braces with the user's data.

Once the user is created, it should appear as shown in the example in the image.

From the user created in the previous step, go to the "Credentials" tab at the top of the window.

Assign a password for the user mifos.

The system will prompt for confirmation. Click the "Save password" button.

Once the password is created, it will be visible in the "Credentials" tab.

4. Create and configure a Client in Keycloak.

To create a client:

• Select the "Clients" section from the left sidebar.

• Press the "Create client" button at the top of the screen.

Enter the requested values:  

Client ID: webapp 

Name: webapp

Press the "Next" button at the bottom of the window.

Note: Replace the values within curly braces with the client’s data.

In the "Compatibility config" section, only the following options should be active:

• Standard flow

• Direct access grants

Enter the requested values:  

Root URL: {$Keycloak_url}/webapp  

Web origins: {$mifos_url}  

Press the "Save" button at the bottom of the window.

Once the configuration is complete, the created client should appear similar to what is shown in the image.

• Go to the "Client scopes" tab at the top of the window.

• Select the "web-app-dedicated" option from the list on the screen.

Press the "Save" button at the center of the window.

The system will display a list of mapper types. From now on, only the type of mapper will be mentioned, assuming it should be selected from this list. Select the "User Property" option. 

Enter the requested values:

Name: usernameInSub

Property: username

Token Claim Name: sub

Claim JSON Type: String

Press the "Save" button.

• Click the "Add mapper" button at the top of the window.

• Select the option “By configuration”.

• Select the "User Session Note" option. 

Enter the requested values:

Name: Client Host

User Session Note: clientHost

Token Claim Name: clientHost

Claim JSON Type: String

Press the "Save" button.

• Add a new mapper.

• Select the "User Session Note" option.

Enter the requested values:

Name: Client IP Address

User Session Note: clientAddress

Token Claim Name: clientAddress

Claim JSON Type: String

Press the "Save" button.

• Add a new mapper.

• Select the "User Session Note" option.

Enter the requested values:

Name: Client ID Address

User Session Note: client_id

Token Claim Name: client_id

Claim JSON Type: String

Press the "Save" button.

Once the configurations are complete, the "web-app-dedicated" section should appear as shown in the image.

5. Set the permissions required for the user in Keycloak.

To create a client:

• Select the "Client scopes" section from the left sidebar.

• Press the "Create client scope" button at the top of the screen.

Enter the requested values:

Name: ALL_FUNCTIONS

Description: ALL_FUNCTIONS

Type: Default

Protocol: OpenID connect

Press the "Save" button.

Once the scope is created, select it.
Click the "Configure a new mapper" button.

Select the "User Realm Role" option.

Enter the requested values:

Name: realm roles 

Token Claim Name: realm_access.roles

Claim JSON Type: String

Press the "Save" button.

6. Configure the environment variables for Apache Fineract.

Set the following env vars for Apache Fineract in the docker-compose.yml file.

Open

• FINERACT_SECURITY_BASICAUTH_ENABLED=false

• FINERACT_SECURITY_OAUTH_ENABLED=true

• FINERACT_SECURITY_2FA_ENABLED=false

• FINERACT_SERVER_OAUTH_RESOURCE_URL=https://{$KEYCLOAK_URL}/realms/{$TENANT}

Validate that containers are lifted correctly:

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

Validate the configurations, by running the following from a terminal:

curl --location --request POST 'https:{$KEYCLOAK_URL}/realms/{$TENANT}/protocol/openid-connect/token' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'username=mifos' --data-urlencode 'password=password' --data-urlencode 'client_id=web-app' --data-urlencode 'grant_type=password' 

Open

Enjoy and give us feedback.

If you require some help please contact us. These are the channels available to get in contact: Communications

Please include screens, logs (use a paste tool like Encrypted note on PrivateBin ), 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.