Mifos X Platform 25.03.22 - Installation Instructions on Windows 11 Home x86_64 - Docker, Postgresql and Oauth

Username

User description

General Public

Users should have basic knowledge about Software Installation on Windows.

Hardware:

• 8Gb RAM 

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

• 32Gb Storage 

Software:

• Windows 11 Home x86_64 Operating System

• Docker 25.03

• Powershell

• Apache Fineract 1.11

1. Install Docker desktop

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

Install Docker Desktop on Windows

Wait for the download file.

Double click on the file that was downloaded

The Installation Wizard will help us to have a graphical UI for the Docker Installation process. Click on the “Ok” button.

The wizard will unpack the files

Once the process is completed click on the “Close and restart” button and the computer will restart.

Once the computer has restarted, the docker subscription screen will open, click the "Accept" button

Select the recommended settings and click the "Finish" button

click "Continue without signing in"

Click the “Skip survey” button.

The Docker Engine will start

In the launch bar, look for the “ Docker Desktop” and start it.

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

We unzip the zip file

We enter the path where the decompressed file is saved

We locate the unzipped file

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

Login to powershell as administrator

On the powershell screen we go to the path where we have the unzipped docker compose file and to the postgresql folder

once in the path and in the folder, we raise the docker compose containers with the command, docker compose up -d

Validate that the three containers are shown on the docker desktop

Web-App

Fineract

Postgresql

We review the Logs to validate that the containers were started correctly. Please be patient, it could take some minutes to complete.

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

We stop the container from the docker desktop interface, click on the "stop" button

The container is stopped

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

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, use a text editor like VScode or Notepad.

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=webapp" ^

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