Mifos X Platform 25.03.22 - Installation Instructions on Linux Ubuntu 24.04 LTS - Docker, 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 24.04 LTS 64 bits Operating System

• Docker 25.03

• MariaDB v11.4

• Apache Fineract 1.11

1. Install Docker 

Go to Docker Download Web Page and select the version for  Ubuntu. 

Install Docker Engine on Ubuntu  

Run the following command to uninstall all conflicting packages

We update the package list

sudo apt-get update

We install the certificates

sudo apt-get install ca-certificates curl

We enter the keys.

sudo install -m 0755 -d /etc/apt/keyrings

sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc

Entering the command grants read, write, and execute permissions to the owner, and read and execute permissions to the group and others.

sudo chmod a+r /etc/apt/keyrings/docker.asc

Add the repository to Apt sources

echo \

  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] Index of linux/ubuntu/ \

  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \

  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Update the package list again

Install the Docker packages.

To install the latest version, run:

sudo apt-get install docker-ce docker-ce-cli http://containerd.io docker-buildx-plugin docker-compose-plugin

Verify that the Docker Engine installation is successful by running the hello-world image.

sudo apt-get install docker-ce docker-ce-cli http://containerd.io docker-buildx-plugin docker-compose-plugin

Linux post-installation steps for Docker Engine

Linux post-installation steps for Docker Engine  

Create the docker group.

Add your user to the docker group.

Note: Integrated the docker group, restart the computer.

Validate that docker is installed.

docker info

Note: if the docker information is not displayed, log out and validate again

2. Download zip file from SourceForge https://sourceforge.net/projects/mifos/files/Mifos%20X/mifosplatform-25.03.22.RELEASE.zip/download 

When you enter the download link, the file will automatically start downloading

We locate the downloaded zip file

Enter the path where the Zip file is located

We unzip the downloaded zip file.

unzip mifosplatform-25.03.22.RELEASE.zip

3. We start the configuration to start the containers in docker.

Enter the mariadb folder

cd ./mifosplatform-25.03.22.RELEASE/docker/mifosx-mariadb

once in the path and in the folder, 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:

Validate that Mifos X Release 25.03 is up and running entering the following url  http://localhost in a Web Browser

Sign in with the default credentials:

User: mifos

Password: password

4. 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 Quay 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.

5. 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.

6. 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.

7. 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.

8. 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.

9. 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.