How to build and run Mifos X Web App UI for Apache Fineract®

Introduction

The Mifos X Web App UI is an Angular-based frontend interface that interacts with the Apache Fineract® backend to provide users with a seamless banking experience. In this guide, we will walk through the steps required to download the Mifos X Web App UI, build it, and configure it to work with a locally running Apache Fineract® backend.

Prerequisites

Node.js (LTS version preferred, example: 22.9.0): This will be the runtime environment.
Angular CLI (16.0.2): a command-line interface tool that you use to initialize, develop, scaffold, and maintain Angular applications directly from a command shell.
Git: You’ll need Git to clone the Mifos X Web App source code from the repository.
A locally running Apache Fineract® backend instance:

Steps to run (only)

Docker:
- You can find pre-built Docker images at the openMF docker repository: https://hub.docker.com/r/openmf/web-app
- Pull image: docker pull openmf/web-app:master
- You can then run a Docker Container from the image:
```
  docker run -d -p 4200:80 openmf/web-app:master
```
- You can also setup different configurations using environment variables:
  - FINERACT_API_URLS: Apache Fineract® servers list (if multiple backends are supported by the UI)
  - FINERACT_API_URL : Default Apache Fineract® backend server URL
  - FINERACT_PLATFORM_TENANTS_IDENTIFIER: Apache Fineract® tenants list (if multiple tenants are supported by the UI)
  - FINERACT_PLATFORM_TENANT_IDENTIFIER: Default Apache Fineract® tenant
  - MIFOS_DISPLAY_TENANT_SELECTOR: Whether tenant selector should be displayed
  The list is not complete!
Testing the Connection:
- After the Mifos X Web App UI is up and running, you can log in using the default Apache Fineract® credentials.
  - Username: mifos
  - Password: password
- Once logged in, you should be able to access the functionalities provided by the Apache Fineract® backend, such as client management, loan management, and more.

Steps to build and run

Clone the Mifos X Web App Repository:
- Open a terminal or command prompt and navigate to the directory where you want to store the Mifos X Web source code.
- Run the following command to clone the repository:
```
git clone https://github.com/openmf/web-app.git
```
Installing Dependencies:
- After cloning the repository, you need to install the required dependencies for the Mifos X Web App UI.
- Navigate to the project directory:
```
cd web-app
```
- Install the dependencies using npm:
```
npm install
```

Configuring the Mifos X Wep App UI to Connect to the Local Backend:

The Mifos X Wep App UI needs to be configured to interact with the locally running Apache Fineract® backend. You can do this by modifying the environment configuration in the UI codebase.
Navigate to the src/environments folder:
```
cd src/environments
```

Open the environment.ts file. Here you can specify the API URL of your local Apache Fineract® backend.

Example:

// The file contents for the current environment will overwrite these during build.
// The build system defaults to the dev environment which uses `environment.ts`, but if you do
// `ng build --env=prod` then `environment.prod.ts` will be used instead.
// The list of which env maps to which file can be found in `.angular-cli.json`.
      
// `.env.ts` is generated by the `npm run env` command
import env from './.env';
      
export const environment = {
  production: false,
  version: env.mifos_x.version,
  hash: env.mifos_x.hash,
  // For connecting to server running elsewhere update the tenant identifier
  fineractPlatformTenantId: window['env']['fineractPlatformTenantId'] || 'default',
  fineractPlatformTenantIds: window['env']['fineractPlatformTenantIds'] || 'default',
  // For connecting to others servers running elsewhere update the base API URL
  baseApiUrls: window['env']['fineractApiUrls'] ||
    'https://dev.mifos.io,https://demo.mifos.io,https://qa.mifos.io,https://staging.mifos.io,https://mobile.mifos.io,https://demo.fineract.dev,https://localhost:8443,'
    + window.location.protocol + '//' + window.location.hostname + ':' + window.location.port,
  // For connecting to server running elsewhere set the base API URL
  baseApiUrl: window['env']['baseApiUrl'] || window.location.protocol + '//' + window.location.hostname + ':' + window.location.port,
  allowServerSwitch: env.allow_switching_backend_instance,
  apiProvider: window['env']['apiProvider'] || '/fineract-provider/api',
  apiVersion: window['env']['apiVersion'] || '/v1',
  serverUrl: '',
  oauth: {
    enabled: false,  // For connecting to Mifos X using OAuth2 Authentication change the value to true
    serverUrl: ''
  },
  warningDialog: {
    title: 'Warning',
    content: 'This system is for authorized use only. Unauthorized access will result in possible legal action. By accessing this system, you acknowledge that you are authorized to do so and that all data stored and processed here is confidential.',
    buttonText: 'Close'
  },
  defaultLanguage: window['env']['defaultLanguage'] || 'en-US',
  supportedLanguages: window['env']['supportedLanguages'] || 'cs-CS,de-DE,en-US,es-MX,fr-FR,it-IT,ko-KO,lt-LT,lv-LV,ne-NE,pt-PT,sw-SW',
  preloadClients: window['env']['preloadClients'] || true,
      
  defaultCharDelimiter: window['env']['defaultCharDelimiter'] || ',',
      
  displayBackEndInfo: window['env']['displayBackEndInfo'] || 'true',
  displayTenantSelector: window['env']['displayTenantSelector'] || 'true',
  // Time in seconds, default 60 seconds
  waitTimeForNotifications: window['env']['waitTimeForNotifications'] || 60,
  // Time in seconds, default 30 seconds
  waitTimeForCOBCatchUp: window['env']['waitTimeForCOBCatchUp'] || 30,
  session: {
    timeout: {
      idleTimeout: window['env']['sessionIdleTimeout'] || 300000, // 5 minutes
    }
  }
};
      
// Server URL
environment.serverUrl = `${environment.baseApiUrl}${environment.apiProvider}${environment.apiVersion}`;
environment.oauth.serverUrl = `${environment.baseApiUrl}${environment.apiProvider}`;

These default values can be overidden via the env.js or env.template.js when Docker is used.
You may also update environment.prod.ts similarly if you plan to build the application in production mode.

Building and Running the Mifos X Web App UI:
- Once the configuration is set, you can build and serve the Mifos X Web App UI.
- Build the application:
```
ng build
```
- To start the development server, run:
```
ng serve
```
  This will start the application on http://localhost:4200. Open the browser and navigate to http://localhost:4200. The UI should now be connected to the locally running Apache Fineract® backend.
- Build Docker image
  - To locally build this Docker image:
    docker build -t openmf/web-app:latest .
  - You can then run a Docker Container from the image:
    docker run -d -p 4200:80 openmf/web-app:latest
- Build with Docker Compose
  - You must have docker and docker-compose installed on your machine
    docker-compose up -d
  - You can also setup different configurations using environment variables:
    - FINERACT_API_URLS: Apache Fineract® servers list (if multiple backends are supported by the UI)
    - FINERACT_API_URL : Default Apache Fineract® backend server URL
    - FINERACT_PLATFORM_TENANTS_IDENTIFIER: Apache Fineract® tenants list (if multiple tenants are supported by the UI)
    - FINERACT_PLATFORM_TENANT_IDENTIFIER: Default Apache Fineract® tenant
    - MIFOS_DISPLAY_TENANT_SELECTOR: Whether tenant selector should be displayed
  The list is not complete!
Testing the Connection:
- After the Mifos X Web App UI is up and running, you can log in using the default Apache Fineract® credentials.
  - Username: mifos
  - Password: password
- Once logged in, you should be able to access the functionalities provided by the Apache Fineract® backend, such as client management, loan management, and more.
Troubleshooting:
- Self-signed certificate issue: Some browsers (like Chrome) will not accept any connection till the user explicitly allows to accept unsecure connection to the backend (self signed certificate generally does not considered safe and user must explicitly tell the browser to connect such host)
  - Possible solutions:
    - Open the browser and navigate to https://localhost:8443/fineract-provider/api/v1
      - Accept the self-signed certificate. Important: You might need to do it multiple times!
    - Add the self-signed certificate into “Trusted Root CA”
    - Disable SSL connection at the Apache Fineract® backend side
- API Errors: If the UI doesn’t connect or fails to fetch data, check if the backend is running. Also, verify that the API paths are correctly set in environment.ts. Also, verify the Self-signed certificate issues.
Conclusion:
- By following these steps, you can easily download, build, and configure the Mifos X Web App UI to connect with a locally running Apache Fineract® backend. This setup enables you to explore, develop, and customize the UI to suit your organization’s needs.
- Feel free to contribute to the open-source community by submitting any issues or pull requests to the Mifos X Web App repository.

Important

Keep in mind that Mifos X Web App is a complex project, and you may encounter issues or need to configure additional settings based on your specific environment and requirements. It’s a good practice to refer to the official Mifos X Web App documentation and the project’s developer community for more details and troubleshooting!