Overview

Mifos® X Web App is a modern single-page application (SPA) built on top of the Mifos® X platform for financial inclusion. It serves as the default web interface for the Mifos® user community.

Technologies Used:

• HTML5, SCSS, and TypeScript
• Angular framework
• Angular Material components

Quick Links

• Live Demo (Updated nightly — sandbox data is reset every 6 hours; test data and transient state may be cleared.)
• GitHub Repository
• Slack Channel
• Jira Board of Mifos
• Jira Board of Mifos Web App Project

Installation Guide

Prerequisites for All Methods

• Git: Download here
• Mifos® X Backend (Apache Fineract®) - Required before running the web app

Backend Setup (REQUIRED FIRST)

Before installing the web app, you need to set up the Apache Fineract® backend server:

1. Choose ONE of these backend options:

   • Option A: Use existing remote server

   • Use the demo (MariaDB) — sandbox data is reset every 6 hours; test data and transient state may be cleared.

   • Use the demo (Keycloak)

   • Use the demo (2FA)

   • Use the demo (Oidc)

   • Use the demo (Postgres)

   • Configure to your server by updating API URLs in environment files

   • Option B: Install local Fineract server

     Installation Guide

   • Option C: Docker Compose for full stack

     • See Docker Compose section below for one-step backend+frontend setup

2. Configure environment files to point to your backend:

   • Update environments/environment.ts (development)
   • Update environments/environment.prod.ts (production)
   • Change OAuth2 settings if needed (disabled by default)

Frontend Setup (Web App)

Choose ONE of the following methods to install the web app:

Method 1: Manual Installation

1. Install Node.js: Download here
2. Install Angular CLI:

   npm install -g @angular/cli@16.0.2
   

3. Clone the repository:

   git clone https://github.com/openMF/web-app.git
   

   For Windows:

   git clone https://github.com/openMF/web-app.git --config core.autocrlf=input
   

4. Navigate to the project directory:
5. Install dependencies:
6. Start the development server:
7. Access the application at http://localhost:4200/

Method 2: Docker Container Only

1. Build the Docker image:

   docker build -t openmf/web-app:latest .
   

2. Run the container:

   docker run -d -p 4200:80 openmf/web-app:latest
   

3. Access the application at http://localhost:4200/

Method 3: Docker Compose (Frontend + Backend)

This sets up both the Mifos® X Web App and Apache Fineract® backend:

1. Clone the repository:

   git clone https://github.com/openMF/web-app.git
   cd web-app
   

   For Windows:

   git clone https://github.com/openMF/web-app.git --config core.autocrlf=input
   cd web-app
   

2. Start Docker Compose:
3. Access the application at http://localhost:4200/

Default Login Credentials

When using the development server with basic authentication:

• Username: mifos
• Password: password

Important: Do not alter these credentials.

Development Commands

• Serve application: ng serve
• Generate new component: ng generate component component-name
• Build for production: ng build --configuration production or npm run build:prod
• Get Angular CLI help: ng help

Proxy Configuration

The web app includes a proxy configuration (proxy.conf.js) that allows you to forward API requests to a remote Fineract backend during local development. This helps avoid CORS issues and enables you to work against production-like environments.

Using the Sandbox Proxy (Default)

By default, the proxy forwards /fineract-provider requests to the Mifos sandbox environment:

• Target: https://demo.mifos.community
• API Endpoint: https://apis.mifos.community (exposed in the demo environment)
• System Reset: Demo test data and transient state are reset every 6 hours (expect data to be periodically cleared).

Sandbox Environment Variables:

FINERACT_API_URLS=https://apis.mifos.community
FINERACT_API_URL=https://apis.mifos.community
FINERACT_API_PROVIDER=/fineract-provider/api
FINERACT_API_ACTUATOR=/fineract-provider
FINERACT_API_VERSION=/v1
FINERACT_PLATFORM_TENANT_IDENTIFIER=default
MIFOS_DEFAULT_LANGUAGE=en-US
MIFOS_SUPPORTED_LANGUAGES=cs-CS,de-DE,en-US,es-MX,fr-FR,it-IT,ko-KO,lt-LT,lv-LV,ne-NE,pt-PT,sw-SW
MIFOS_PRELOAD_CLIENTS=true
MIFOS_DEFAULT_CHAR_DELIMITER=,

Using a Local Fineract Instance

To proxy to a local Fineract server instead:

Use the provided localhost proxy file (recommended for ng serve):

1. Start the dev server with the localhost proxy:

   ng serve --proxy-config proxy.localhost.conf.js

2. Ensure your local Fineract instance is running on http://localhost:8443.

Notes:

• proxy.localhost.conf.js forwards /fineract-provider to your local backend to avoid CORS during development.
• The HttpsProxyAgent / setupForProxy logic (present in proxy.conf.js) is only necessary when an upstream corporate/HTTP proxy must be used (set via HTTP_PROXY/http_proxy). It is not required for a direct localhost backend.

Proxy Features

• CORS Avoidance: Eliminates cross-origin issues during local development
• Error Handling: Gracefully handles proxy failures with detailed logging
• Corporate Proxy Support: Maintains support for corporate proxy agents via HTTP_PROXY environment variable
• Debug Logging: All proxy requests are logged for troubleshooting

The proxy is configured to work with Fineract endpoints as described in this section.

Testing the Proxy

To verify the proxy is working correctly, start the development server (ng serve) and test with curl:

Successful proxy request:

curl -i "http://localhost:4200/fineract-provider/api/v1/runreports/FullClientReport?R_officeId=1&output-type=HTML&R_loanOfficerId=-1"

Expected: HTTP 200 response with proxied data from the demo environment. Server console shows:

[Proxy] Proxying: GET /fineract-provider/api/v1/runreports/... -> https://demo.mifos.community/api/v1/runreports/...

Simulated proxy error (backend unreachable):

If the backend is unreachable or returns an error, the proxy returns HTTP 502:

# Stop your Fineract backend (if using localhost) or test with an invalid target
# The proxy will log the error and return:

Server console (example):

[Proxy] Error while proxying request: GET /fineract-provider/... -> https://demo.mifos.community - ECONNREFUSED

HTTP response:

HTTP/1.1 502 Bad Gateway
Content-Type: text/plain

Proxy error: connect ECONNREFUSED

Configuration Options

Environment Variables for Docker

All these environment variables can be set when using Docker or Docker Compose:

Fineract Backend Settings

Language Settings (i18n)

Date and Datetime Format Settings

These environment variables control the default date and datetime formats used throughout the Mifos® X Web App. They can be set in your Docker environment, in the env.js/env.template.js files, or in your deployment environment.

• MIFOS_DEFAULT_FORMAT_DATE sets the default format for displaying dates (e.g., 15 February 2026).
• MIFOS_DEFAULT_FORMAT_DATETIME sets the default format for displaying date and time (e.g., 15 February 2026 14:30:00).

If a user does not select a custom format in the UI, these values are used as the fallback. You can override them per user in the Settings screen.

How to set:

In Docker Compose or Docker:

MIFOS_DEFAULT_FORMAT_DATE=yyyy-MM-dd
MIFOS_DEFAULT_FORMAT_DATETIME=yyyy-MM-dd HH:mm

In src/assets/env.template.js:

window['env']['defaultFormatDate'] = '$MIFOS_DEFAULT_FORMAT_DATE';
window['env']['defaultFormatDatetime'] = '$MIFOS_DEFAULT_FORMAT_DATETIME';

Where used:

These values are read by the application when it starts and are used as the default for date and datetime display in forms, tables, and reports.

Available languages:

Session & Performance Settings

Password Policy Settings

Password validation for Basic Authentication can be configured via environment variables.

Behavior:

• If MIFOS_MIN_PASSWORD_LENGTH is not set, it defaults to 8.
• If MIFOS_PASSWORD_REGEX is not set, the application falls back to the built-in password validation policy.
• These settings apply only to Basic Authentication login and user password validation.
• OAuth/OIDC flows are not affected.

Docker Example:

MIFOS_MIN_PASSWORD_LENGTH=8
MIFOS_PASSWORD_REGEX=^(?=.*[A-Z])(?=.*[a-z])(?=.*\d).{8,50}$

UI Display Settings

OAUTH Settings

OIDC Settings

External National ID System Integration

These variables enable automatic lookup and auto-fill of client data from an external National ID system (e.g., Mexico's CURP) during client creation and editing.

When ENABLE_EXTERNAL_NATIONAL_ID_SYSTEM is set to true, the following fields are auto-filled and disabled during client creation/editing after a successful lookup:

• First Name
• Middle Name
• Last Name
• Date of Birth
• Gender

The user types the External ID value, and if it matches the configured regex, the system calls the external API to retrieve and auto-fill client information.

Docker Compose with External National ID:

docker-compose -f docker-compose.yml -f docker-compose.external-nationalid.yml up -d

For more detailed configuration options, refer to the env.sample file in the root directory of the project.

Interbank Transfers Settings

Remittance Module Settings

These variables configure the Remittance Module, which provides a 7-step wizard for processing remittance payouts (search, validate recipient, assign payout, confirm payment, and generate receipt).

When MIFOS_REMITTANCE_ENABLED is set to true, a "Remittances" menu item appears in the sidenav and the /remittances route becomes accessible. The module supports the following workflow:

1. Search Remittance — Look up a transaction by vendor and external reference ID
2. Remittance Details — Review transaction details and status
3. Search Beneficiary — Validate the recipient's identity documents
4. Beneficiary Details — Review validated recipient info and assign to a Mifos client
5. Transactional Profile — Register the transactional profile and assign payout
6. Confirm Payment — Final confirmation before payout
7. Payment Receipt — View and print the payment receipt

Client Data Masking Example

When MIFOS_COMPLIANCE_HIDE_CLIENT_DATA=false (default):

EMANUEL CASTILLO MIGUEL TECO

When MIFOS_COMPLIANCE_HIDE_CLIENT_DATA=true:

E***** C******* M***** T***

This applies to client name display, e.g. in Institution/Clients list.

Interbank Transfer Menu

By default, the “Interbank Transfer” menu will be displayed in the hamburger menu of the Savings account.

Role-Based Access Control (RBAC)

What is RBAC? Role-Based Access Control restricts system access and functionality based on user roles and permissions. When enabled, menus and buttons in the WebApp are shown/hidden based on the user's assigned permissions.

When to enable RBAC:

• Production environments where strict access control is required
• Multi-tenant systems with different user roles (Teller, Field Officer, Loan Reviewer, etc.)
• Compliance requirements that mandate role-based permissions

Default Behavior (RBAC Disabled): By default, MIFOS_PRODUCTION_MODE_ENABLE_RBAC=false maintains backward compatibility:

• All menus and buttons are visible to all logged-in users
• Existing deployments continue to work without configuration changes
• Suitable for development, testing, or single-user scenarios

When RBAC is Enabled: Set MIFOS_PRODUCTION_MODE_ENABLE_RBAC=true to activate permission-based UI control:

• Menus (Institution, Admin, Reports, Accounting) require specific READ permissions
• Buttons (Create, Edit, Delete, Approve, etc.) require corresponding permissions
• Users see only features they have permissions for
• Important: You must configure roles in Apache Fineract® before enabling RBAC

How to enable RBAC:

1. Configure environment variable:

   MIFOS_PRODUCTION_MODE_ENABLE_RBAC=true

2. Create roles in Fineract Admin Panel:

   • Navigate to: Admin → System → Manage Roles
   • Create roles (e.g., Teller, Field Officer, Loan Reviewer, etc.)
   • Assign appropriate permissions to each role

3. Assign roles to users:

   • Navigate to: Admin → Users → Edit User
   • Select appropriate role for each user

Common role examples include:

• Teller: Cash operations (deposits, withdrawals, repayments)
• Field Officer: Client onboarding, loan origination
• Loan Reviewer: Credit analysis, loan approval/rejection
• Treasurer: Disbursement, accounting, fund movements
• KYC Officer: Client identity verification
• PLD Officer (AML): Anti-money laundering monitoring
• Product Owner: Product and system configuration

Releases

1.0.0 (Tag: 1.0.0-fineract1.11)

This is the first official release of the Mifos® X web application:

• Developed for Apache Fineract® 1.11
• No Self Service area
• GLIM support limited
• JLG not yet supported
• Surveys not yet supported

Contributing

We welcome contributions! Please read our contribution guidelines before submitting pull requests.

Related Projects

Apache Fineract - Apache Fineract® provides open APIs and affordable core banking solution for financial institutions and is the backend for all UIs of the Mifos®.