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

• Docker 25.03

• MariaDB v11.4

• Apache Fneract 1.11

1. Install Docker 

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

https://docs.docker.com/engine/install/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] https://download.docker.com/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

https://docs.docker.com/engine/install/linux-postinstall/  

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

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

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

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