Update README.md (#2337)
This commit is contained in:
Jayesh Savaliya
@@ -1,242 +1,189 @@
|
|||||||
# Mifos X Web App  [testRigor](https://app.testrigor.com/public/X3THbQd9nxLMxkdPu) [Slack](https://app.slack.com/client/T0F5GHE8Y/CJJGJLN10)
|
# Mifos X Web App 
|
||||||
|
|
||||||
Mifos X Web App is the revamped version of the Mifos X Community App, an effective financial inclusion solution and the default web application built on top of the Mifos X platform for the Mifos User Community.
|
## Overview
|
||||||
|
|
||||||
It is a Single-Page App (SPA) written in standard web technologies [HTML5](http://whatwg.org/html), [SCSS](http://sass-lang.com) and [TypeScript](http://www.typescriptlang.org). It leverages the popular [Angular](https://angular.io/) framework and [Angular Material](https://material.angular.io/) for material design components.
|
Mifos X Web App is a modern Single-Page Application (SPA) built on top of the Mifos X platform for financial inclusion. It's the revamped version of the Mifos X Community App, serving as the default web interface for the Mifos User Community.
|
||||||
|
|
||||||
## Getting started using
|
**Technologies Used:**
|
||||||
|
- HTML5, SCSS, and TypeScript
|
||||||
The latest code is continuously deployed at [https://sandbox.mifos.community/#/login](https://sandbox.mifos.community/#/login) every night.
|
- Angular framework
|
||||||
|
- Angular Material components
|
||||||
## Getting started developing
|
|
||||||
|
## Quick Links
|
||||||
1. Ensure you have the following installed in your system:
|
- [Live Demo](https://sandbox.mifos.community/#/login) (Updated nightly)
|
||||||
|
- [GitHub Repository](https://github.com/openMF/web-app)
|
||||||
[`git`](https://git-scm.com/downloads)
|
- [TestRigor](https://app.testrigor.com/public/X3THbQd9nxLMxkdPu)
|
||||||
|
- [Slack Channel](https://app.slack.com/client/T0F5GHE8Y/CJJGJLN10)
|
||||||
[`nodeJs`](https://nodejs.org/en/download/)
|
- [Jira Board](https://mifosforge.jira.com/jira/your-work)
|
||||||
|
- [Jira Web App Project](https://mifosforge.jira.com/jira/software/c/projects/WEB/boards/62)
|
||||||
2. Install [angular-cli](https://github.com/angular/angular-cli) globally.
|
|
||||||
|
## Installation Guide
|
||||||
```
|
|
||||||
npm install -g @angular/cli@16.0.2
|
### Prerequisites for All Methods
|
||||||
```
|
- Git: [Download here](https://git-scm.com/downloads)
|
||||||
|
- Mifos X Backend (Fineract) - **Required before running the web app**
|
||||||
3. Clone the project locally into your system.
|
|
||||||
|
### Backend Setup (REQUIRED FIRST)
|
||||||
```
|
|
||||||
git clone https://github.com/openMF/web-app.git
|
Before installing the web app, you need to set up the Fineract backend server:
|
||||||
```
|
|
||||||
|
1. **Choose ONE of these backend options:**
|
||||||
4. `cd` into project root directory and make sure you are on the master branch.
|
|
||||||
|
- **Option A: Use existing remote server**
|
||||||
5. Install the dependencies.
|
- Use the sandbox at `https://sandbox.mifos.community`
|
||||||
|
- Use the demo at `https://demo.mifos.community`
|
||||||
```
|
- Configure to your server by updating API URLs in environment files
|
||||||
npm install
|
|
||||||
```
|
- **Option B: Install local Fineract server**
|
||||||
|
- For Windows: [Installation Guide](https://cwiki.apache.org/confluence/display/FINERACT/Fineract-platform+Installation+on+Windows)
|
||||||
6. To preview the app, run the following command and navigate to `http://localhost:4200/`.
|
- For Ubuntu: [Installation Guide](https://cwiki.apache.org/confluence/display/FINERACT/Fineract+Installation+on+Ubuntu+Server)
|
||||||
|
|
||||||
```
|
- **Option C: Docker Compose for full stack**
|
||||||
ng serve
|
- See Docker Compose section below for one-step backend+frontend setup
|
||||||
```
|
|
||||||
|
2. **Configure environment files to point to your backend:**
|
||||||
The application is using the development server with basic authentication by default. The credentials for the same are:
|
- Update `environments/environment.ts` (development)
|
||||||
|
- Update `environments/environment.prod.ts` (production)
|
||||||
Username - mifos
|
- Change OAuth2 settings if needed (disabled by default)
|
||||||
Password - password
|
|
||||||
|
### Frontend Setup (Web App)
|
||||||
**Important Note:** Please do not make any alterations to these credentials.
|
|
||||||
|
Choose ONE of these methods to install the web app:
|
||||||
### Development server
|
|
||||||
|
#### Method 1: Manual Installation
|
||||||
Run `ng serve` for a dev server. Navigate to `http://localhost:4200/`. The app will automatically reload if you change any of the source files.
|
|
||||||
|
1. Install Node.js: [Download here](https://nodejs.org/en/download/)
|
||||||
### Code scaffolding
|
2. Install Angular CLI:
|
||||||
|
```
|
||||||
Run `ng generate component component-name` to generate a new component. You can also use
|
npm install -g @angular/cli@16.0.2
|
||||||
`ng generate directive|pipe|service|class|guard|interface|enum|module`.
|
```
|
||||||
|
3. Clone the repository:
|
||||||
### Build
|
```
|
||||||
|
git clone https://github.com/openMF/web-app.git
|
||||||
Run `ng build` to build the project. The build artifacts will be stored in the `dist/` directory. Use the `--configuration production` flag for a production build.
|
```
|
||||||
|
For Windows:
|
||||||
Run `npm run build:prod` to build a production artifacts Instead.
|
```
|
||||||
|
git clone https://github.com/openMF/web-app.git --config core.autocrlf=input
|
||||||
### Further help
|
```
|
||||||
|
4. Navigate to the project directory:
|
||||||
To get more help on the Angular CLI use `ng help` or go check out the
|
```
|
||||||
[Angular-CLI README](https://github.com/angular/angular-cli).
|
cd web-app
|
||||||
|
```
|
||||||
## Setting up a local server
|
5. Install dependencies:
|
||||||
|
```
|
||||||
Follow the given instructions for your operating system to setup a local server for the Mifos X platform.
|
npm install
|
||||||
|
```
|
||||||
[Windows](https://cwiki.apache.org/confluence/display/FINERACT/Fineract-platform+Installation+on+Windows)
|
6. Start the development server:
|
||||||
|
```
|
||||||
[Ubuntu](https://cwiki.apache.org/confluence/display/FINERACT/Fineract+Installation+on+Ubuntu+Server)
|
ng serve
|
||||||
|
```
|
||||||
For connecting to server running elsewhere update the base API URL and/or tenant identifier property in the `environments/environment.ts` file and `environments/environment.prod.ts` file for development and production use respectively.
|
7. Access the application at `http://localhost:4200/`
|
||||||
|
|
||||||
By default OAuth2 is disabled. To enable it, change the value of oauth.enabled property to true in the `environments/environment.ts` file and `environments/environment.prod.ts` file for development and production use respectively.
|
#### Method 2: Docker Container Only
|
||||||
|
|
||||||
### Docker
|
1. Build the Docker image:
|
||||||
|
```
|
||||||
To locally build this Docker image from source (after `git clone` this repo), run:
|
docker build -t openmf/web-app:latest .
|
||||||
|
```
|
||||||
```
|
2. Run the container:
|
||||||
docker build -t openmf/web-app:latest .
|
```
|
||||||
```
|
docker run -d -p 4200:80 openmf/web-app:latest
|
||||||
|
```
|
||||||
You can then run a Docker Container from the image above like this:
|
3. Access the application at `http://localhost:4200/`
|
||||||
|
|
||||||
```
|
#### Method 3: Docker Compose (Frontend + Backend)
|
||||||
docker run -d -p 4200:80 openmf/web-app:latest
|
|
||||||
```
|
This sets up both the Mifos X Web App and Fineract backend:
|
||||||
|
|
||||||
Access the webapp on http://localhost:4200 in your browser.
|
1. Clone the repository:
|
||||||
|
```
|
||||||
### Docker compose
|
git clone https://github.com/openMF/web-app.git
|
||||||
|
cd web-app
|
||||||
It is possible to do a 'one-touch' installation of Mifos X Web App using containers (AKA "Docker").
|
```
|
||||||
Fineract now packs the Mifos community-app web UI in it's docker deploy.
|
For Windows:
|
||||||
|
```
|
||||||
As Prerequisites, you must have `docker` and Docker Compose v2 or later installed on your machine; see
|
git clone https://github.com/openMF/web-app.git --config core.autocrlf=input
|
||||||
[Docker Install](https://docs.docker.com/install/) and
|
cd web-app
|
||||||
[Docker Compose Install](https://docs.docker.com/compose/install/).
|
```
|
||||||
|
2. Start Docker Compose:
|
||||||
Now to run a new MifosX Web App instance you can simply:
|
```
|
||||||
|
docker compose up -d
|
||||||
1. `git clone https://github.com/openMF/web-app.git ; cd web-app`
|
```
|
||||||
1. for windows, use `git clone https://github.com/openMF/web-app.git --config core.autocrlf=input ; cd web-app`
|
3. Access the application at `http://localhost:4200/`
|
||||||
1. `docker compose up -d`
|
|
||||||
1. Access the webapp on http://localhost:4200 in your browser.
|
## Default Login Credentials
|
||||||
|
|
||||||
You can also setup different configurations for the MifosX Web App using environment variables:
|
When using the development server with basic authentication:
|
||||||
|
- **Username:** mifos
|
||||||
1. Use environment variables (best choice if you run with Docker Compose):
|
- **Password:** password
|
||||||
|
|
||||||
Fineract backend settings
|
**Important:** Do not alter these credentials.
|
||||||
|
|
||||||
```
|
## Development Commands
|
||||||
FINERACT_API_URLS
|
|
||||||
```
|
- **Serve application:** `ng serve`
|
||||||
|
- **Generate new component:** `ng generate component component-name`
|
||||||
Value to set a Fineract server list (environments) to be used, Default value:
|
- **Build for production:** `ng build --configuration production` or `npm run build:prod`
|
||||||
|
- **Get Angular CLI help:** `ng help`
|
||||||
```
|
|
||||||
https://sandbox.mifos.community,https://demo.mifos.community,https://localhost:8443
|
## Configuration Options
|
||||||
```
|
|
||||||
|
### Environment Variables for Docker
|
||||||
```
|
|
||||||
FINERACT_API_URL
|
All these environment variables can be set when using Docker or Docker Compose:
|
||||||
```
|
|
||||||
|
#### Fineract Backend Settings
|
||||||
Default value used from the Fineract server list. Default value:
|
| Variable | Description | Default Value |
|
||||||
|
|----------|-------------|---------------|
|
||||||
```
|
| FINERACT_API_URLS | Fineract server list | https://sandbox.mifos.community,https://demo.mifos.community,https://localhost:8443 |
|
||||||
https://localhost:8443
|
| FINERACT_API_URL | Default Fineract server | https://localhost:8443 |
|
||||||
```
|
| FINERACT_PLATFORM_TENANT_IDENTIFIER | Default tenant identifier (must align with Fineract `tenants` table) | default |
|
||||||
|
| FINERACT_PLATFORM_TENANTS_IDENTIFIER | Tenant identifier list (must align with Fineract `tenants` table) | - |
|
||||||
```
|
|
||||||
FINERACT_PLATFORM_TENANT_IDENTIFIER
|
#### Language Settings (i18n)
|
||||||
```
|
| Variable | Description | Default Value |
|
||||||
|
|----------|-------------|---------------|
|
||||||
Fineract Tenant identifier to be used by default, It must be aligned with the Fineract `tenants` table. Default value:
|
| MIFOS_DEFAULT_LANGUAGE | Default language | en-US |
|
||||||
|
| MIFOS_SUPPORTED_LANGUAGES | List of 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 |
|
||||||
```
|
|
||||||
default
|
Available languages:
|
||||||
```
|
|
||||||
|
| Language | Code | File |
|
||||||
```
|
|----------|------|------|
|
||||||
FINERACT_PLATFORM_TENANTS_IDENTIFIER
|
| Czech | cs | cs-CS.json |
|
||||||
```
|
| German | de | de-DE.json |
|
||||||
|
| English | en | en-US.json |
|
||||||
Fineract Tenant identifier list to be used, Those must be aligned with the Fineract `tenants` table.
|
| Spanish | es | es-MX.json |
|
||||||
|
| French | fr | fr-FR.json |
|
||||||
Setting for Languages (i18n) still under development
|
| Italian | it | it-IT.json |
|
||||||
|
| Korean | ko | ko-KO.json |
|
||||||
```
|
| Lithuanian | li | li-LI.json |
|
||||||
MIFOS_DEFAULT_LANGUAGE=en-US
|
| Latvian | lv | lv-LV.json |
|
||||||
```
|
| Nepali | ne | ne-NE.json |
|
||||||
|
| Portuguese | pt | pt-PT.json |
|
||||||
```
|
| Swahili | sw | sw-SW.json |
|
||||||
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
|
|
||||||
```
|
#### Session & Performance Settings
|
||||||
|
| Variable | Description | Default Value |
|
||||||
These are the Language available now:
|
|----------|-------------|---------------|
|
||||||
|
| MIFOS_SESSION_IDLE_TIMEOUT | Session timeout in milliseconds | 300000 |
|
||||||
```
|
| MIFOS_PRELOAD_CLIENTS | Whether to preload clients in Clients view | true |
|
||||||
MIFOS_SESSION_IDLE_TIMEOUT=300000
|
| MIFOS_DEFAULT_CHAR_DELIMITER | Character delimiter for CSV exports | , |
|
||||||
```
|
| MIFOS_WAIT_TIME_FOR_NOTIFICATIONS | Wait time in seconds for reading notifications | 60 |
|
||||||
|
| MIFOS_WAIT_TIME_FOR_CATCHUP | Wait time in seconds for reading COB Catch-Up status | 30 |
|
||||||
Time in milliseconds for Session idle timeout, default 300000 seconds
|
|
||||||
|
#### UI Display Settings
|
||||||
| Language | Code | File |
|
| Variable | Description | Default Value |
|
||||||
| :--------: | :--: | :--------: |
|
|----------|-------------|---------------|
|
||||||
| Czech | cs | cs-CS.json |
|
| MIFOS_DISPLAY_TENANT_SELECTOR | Display tenant selector in Login view | true |
|
||||||
| German | de | de-DE.json |
|
| MIFOS_DISPLAY_BACKEND_INFO | Display backend info in footer | true |
|
||||||
| English | en | en-US.json |
|
|
||||||
| Spanish | es | es-MX.json |
|
For more detailed configuration options, refer to the `env.sample` file in the root directory of the project.
|
||||||
| French | fr | fr-FR.json |
|
|
||||||
| Italian | it | it-IT.json |
|
## Contributing
|
||||||
| Korean | ko | ko-KO.json |
|
|
||||||
| Lithuanian | li | li-LI.json |
|
We welcome contributions! Please read our [contribution guidelines](.github/CONTRIBUTING.md) before submitting pull requests.
|
||||||
| Latvian | lv | lv-LV.json |
|
|
||||||
| Nepali | ne | ne-NE.json |
|
## Related Projects
|
||||||
| Portuguese | pt | pt-PT.json |
|
|
||||||
| Swahili | sw | sw-SW.json |
|
[Apache Fineract](https://github.com/apache/fineract) - Apache Fineract provides open APIs and affordable core banking solution for financial institutions and it is the backend for all UIs of the Mifos.
|
||||||
|
|
||||||
Setting for applying the Client preload in the Clients view, Default true
|
|
||||||
|
|
||||||
```
|
|
||||||
MIFOS_PRELOAD_CLIENTS=false
|
|
||||||
```
|
|
||||||
|
|
||||||
Setting for exporting report table to CSV file using this field delimiter
|
|
||||||
|
|
||||||
```
|
|
||||||
MIFOS_DEFAULT_CHAR_DELIMITER=,
|
|
||||||
```
|
|
||||||
|
|
||||||
Setting for Wait time in seconds for reading the user notifications, Default 60 seconds
|
|
||||||
|
|
||||||
```
|
|
||||||
MIFOS_WAIT_TIME_FOR_NOTIFICATIONS=60
|
|
||||||
```
|
|
||||||
|
|
||||||
Setting for Wait time in seconds for reading the COB Catch-Up status, Default 30 seconds
|
|
||||||
|
|
||||||
```
|
|
||||||
MIFOS_WAIT_TIME_FOR_CATCHUP=30
|
|
||||||
```
|
|
||||||
|
|
||||||
Setting for display or hide the Tenant selector in the Login view (mainly for Production environments and for security reasons), Default true
|
|
||||||
|
|
||||||
```
|
|
||||||
MIFOS_DISPLAY_TENANT_SELECTOR=false
|
|
||||||
```
|
|
||||||
|
|
||||||
Setting for display or hide the Backend info (url) in the footer part (mainly for security reasons), Default true
|
|
||||||
|
|
||||||
```
|
|
||||||
MIFOS_DISPLAY_BACKEND_INFO=false
|
|
||||||
```
|
|
||||||
|
|
||||||
For more information look the env.sample file in the root directory of the project
|
|
||||||
|
|
||||||
# Jira Links
|
|
||||||
|
|
||||||
Jira Board Link: [Kanban Board]
|
|
||||||
https://mifosforge.jira.com/jira/your-work
|
|
||||||
|
|
||||||
Jira Web App Project Link:
|
|
||||||
https://mifosforge.jira.com/jira/software/c/projects/WEB/boards/62
|
|
||||||
|
|
||||||
## Want to help? [](https://github.com/openMF/web-app/issues)
|
|
||||||
|
|
||||||
Want to file a bug, request a feature, contribute some code, or improve documentation? Excellent! Read up on our guidelines for [contributing](.github/CONTRIBUTING.md) and then check out one of our [issues](https://github.com/openMF/web-app/issues). Make sure you follow the guidelines before sending a contribution!
|
|
||||||
|
|
||||||
Apache Fineract provides open APIs and affordable core banking solution for financial institutions
|
|
||||||
and it is the backend for all UIs of the Mifos. Its GitHub Repository is (https://github.com/apache/fineract)
|
|
||||||
|
|||||||
Reference in New Issue
Block a user