Mifos® X Web App

June 3, 2026 · View on GitHub

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 20 framework
  • Angular Material components

📋 Table of Contents

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@20.3.27
  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: 
    cd web-app
  5. Install dependencies: 
    npm install
  6. Start the development server: 
    ng serve
  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: 
    docker compose up -d
  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

VariableDescriptionDefault Value
FINERACT_API_URLSFineract server listhttps://demo.mifos.community,https://localhost:8443
FINERACT_API_URLDefault Fineract serverhttps://localhost:8443
FINERACT_API_ACTUATORDefault Fineract Actuator endpoint/fineract-provider
FINERACT_PLATFORM_TENANT_IDENTIFIERDefault tenant identifier (must align with Fineract tenants table)default
FINERACT_PLATFORM_TENANTS_IDENTIFIERTenant identifier list (must align with Fineract tenants table)-

Language Settings (i18n)

VariableDescriptionDefault Value
MIFOS_DEFAULT_LANGUAGEDefault languageen-US
MIFOS_SUPPORTED_LANGUAGESList of supported languagescs-CS,de-DE,en-US,es-MX,fr-FR,it-IT,ko-KO,lt-LT,lv-LV,ne-NE,pt-PT,sw-SW

Date and Datetime Format Settings

VariableDescriptionDefault Value
MIFOS_DEFAULT_FORMAT_DATEDefault date format for the applicationdd MMMM yyyy
MIFOS_DEFAULT_FORMAT_DATETIMEDefault datetime format for the applicationdd MMMM yyyy HH:mm:ss

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:

LanguageCodeFile
Czechcscs-CS.json
Germandede-DE.json
Englishenen-US.json
Spanisheses-MX.json
Frenchfrfr-FR.json
Italianitit-IT.json
Koreankoko-KO.json
Lithuanianltlt-LT.json
Latvianlvlv-LV.json
Nepalinene-NE.json
Portugueseptpt-PT.json
Swahiliswsw-SW.json

Session & Performance Settings

VariableDescriptionDefault Value
MIFOS_SESSION_IDLE_TIMEOUTSession timeout in milliseconds300000
MIFOS_PRELOAD_CLIENTSWhether to preload clients in Clients viewtrue
MIFOS_DEFAULT_CHAR_DELIMITERCharacter delimiter for CSV exports,
MIFOS_WAIT_TIME_FOR_NOTIFICATIONSWait time in seconds for reading notifications60
MIFOS_WAIT_TIME_FOR_CATCHUPWait time in seconds for reading COB Catch-Up status30
MIFOS_HTTP_CACHE_ENABLEDwhether to use HTTP Get calls with cachefalse

Password Policy Settings

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

VariableDescriptionDefault Value
MIFOS_MIN_PASSWORD_LENGTHMinimum required password length8
MIFOS_PASSWORD_REGEXRegex pattern used to validate password strengthDefault policy

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

VariableDescriptionDefault Value
MIFOS_DISPLAY_TENANT_SELECTORDisplay tenant selector in Login viewtrue
MIFOS_DISPLAY_BACKEND_INFODisplay backend info in footertrue
MIFOS_PRODUCTION_MODEShow minimal production hero on login pagefalse
MIFOS_ALLOW_SERVER_SWITCH_SELECTORDisplay DNS server listtrue
MIFOS_COMPLIANCE_HIDE_CLIENT_DATAHide client names in UI (mask with *)false
MIFOS_PRODUCTION_MODE_ENABLE_RBACEnable Role-Based Access Control for menus/buttonsfalse

OAUTH Settings

VariableDescriptionDefault Value
MIFOS_OAUTH_SERVER_ENABLEDEnable the use of OAuth2 serverfalse
MIFOS_OAUTH_SERVER_URLSet the OAuth2 server URL (issuer)
MIFOS_OAUTH_SERVER_LOGOUT_URLSet the OAuth2 server logout URL
MIFOS_OAUTH_CLIENT_IDSet the OAuth2 Client Id
MIFOS_OAUTH_AUTHORIZE_URLSet the OAuth2 authorization endpoint URL
MIFOS_OAUTH_TOKEN_URLSet the OAuth2 token endpoint URL
MIFOS_OAUTH_REDIRECT_URISet the OAuth2 redirect URI after authentication
MIFOS_OAUTH_SCOPESet the OAuth2 scopes (e.g., openid profile)

OIDC Settings

VariableDescriptionDefault Value
FINERACT_PLUGIN_OIDC_ENABLEDEnable the use of Oidc serverfalse
FINERACT_PLUGIN_OIDC_BASE_URLSet the Oidc server URL
FINERACT_PLUGIN_OIDC_CLIENT_IDSet the Client Id
FINERACT_PLUGIN_OIDC_API_URLSet the Client API URL
FINERACT_PLUGIN_OIDC_FRONTEND_URLSet the Front End URL callback

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.

VariableDescriptionDefault Value
ENABLE_EXTERNAL_NATIONAL_ID_SYSTEMSet to true to enable External National ID lookupfalse
EXTERNAL_NATIONAL_ID_SYSTEM_URLURL of the external National ID API
EXTERNAL_NATIONAL_ID_SYSTEM_API_HEADERHeader name for the external API key (e.g., X-Gravitee-Api-Key)
EXTERNAL_NATIONAL_ID_SYSTEM_API_KEYAPI key value (injected server-side via nginx; keep empty in source control)
EXTERNAL_NATIONAL_ID_REGEXRegex pattern to validate the external ID format (e.g., CURP)
EXTERNAL_NATIONALID_API_URLFull upstream URL for nginx proxy_pass

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

VariableDescriptionDefault Value
MIFOS_INTERBANK_TRANSFERS_API_URLThe Interbank server urlhttps://apis.mifos.community
MIFOS_INTERBANK_TRANSFERS_API_PROVIDERThe Interbank server endpoint/vnext2
MIFOS_INTERBANK_TRANSFERS_API_VERSIONThe Interbank server api version/v1.0
MIFOS_INTERBANK_TRANSFERS_ENABLEDIf the Interbank feature is enabledtrue

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

VariableDescriptionDefault Value
MIFOS_REMITTANCE_API_URLThe Remittance Microservice server URLhttps://apis.mifos.community
MIFOS_REMITTANCE_API_PROVIDERThe Remittance server endpoint/1.0/remittance
MIFOS_REMITTANCE_API_VERSIONThe Remittance server API version/v1
MIFOS_REMITTANCE_ENABLEDIf the Remittance feature is enabledfalse
MIFOS_REMITTANCE_API_HEADERAPI gateway auth header nameX-Gravitee-Api-Key
MIFOS_REMITTANCE_API_KEYAPI key for the Remittance gateway

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.

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