Open in app

Sign in

Write

Sign in

Fineract — Core Banking Installation & Setup

D Kuruppath
7 min readApr 30, 2024

Introduction

This document will outline the step by step instructions to install Apache Fineract Core Banking platform.

I couldn't find an end to end Apache Fineract installation guide, and hence the existence of this article / document.

We are on our BIAN Capability Journey, and are leveraging Apache Fineract for our PoC’s / Use cases.

What exactly is Fineract ?

Its a core banking platform for a financial organization / bank. Refer — https://fineract.apache.org — for further information

System Configuration

  • VM Configuration — 3 CPU, 6 GB RAM
  • OS : Ubuntu 20.04
  • Java v17
  • Apache Tomcat 10
  • MySQL 8.0.36

Tech Installation

  • Install Java 17
  • Download and unzip Apache Tomcat 10 (only if installing MIFOS UI, covered as Option#2 in the document below).
  • If you are using any other UI, then use instructions accordingly.

Install & Configure Backend (Database)

Install MySQL

$ sudo apt update
$ sudo apt install mysql-server
$ sudo systemctl start mysql.service

Set MySQL Default Credentials

$ sudo mysql
mysql> ALTER USER ‘root’@’localhost’ IDENTIFIED WITH mysql_native_password BY ‘buildFineract11’;
Query OK, 0 rows affected (0.00 sec)
mysql> CREATE USER 'fineract'@'%' IDENTIFIED BY 'fineract';
Query OK, 0 rows affected (0.00 sec)
mysql> GRANT ALL PRIVILEGES ON *.* TO 'fineract'@'%';
Query OK, 0 rows affected (0.00 sec)
mysql> FLUSH PRIVILEGES;
Query OK, 0 rows affected (0.01 sec)

Create Fineract DB Schema

Configure gradle build properties

root@dev01:/opt/fineract$ vi /opt/fineract/fineract-provider/build.gradle
...
project.ext.mysqlUser='fineract'
project.ext.mysqlPassword='fineract'
...

task createDB {
  description= "Creates the MariaDB Database. Needs database name to be passed (like: -PdbName=someDBname)"
  doLast {
  // def sql = Sql.newInstance( 'jdbc:mariadb://localhost:3306/', mysqlUser, mysqlPassword, 'org.mariadb.jdbc.Driver' )
  def sql = Sql.newInstance( 'jdbc:mysql://localhost:3306/', mysqlUser, mysqlPassword, 'com.mysql.cj.jdbc.Driver' )
  sql.execute( 'CREATE DATABASE '+"`$dbName` CHARACTER SET utf8mb4" )
  }
}

Finally, create the schema

# Default tenants
root@dev01:/opt/fineract$ ./gradlew createDB -PdbName=fineract_tenants

# Defaults DB
root@dev01:/opt/fineract$ ./gradlew createDB -PdbName=fineract_default

Download MySQL Client jar

# get link of jar from path
https://downloads.mysql.com/archives/c-j/

# Find MySQL Version first
root@dev01:/opt/fineract$ mysql -V
mysql Ver 8.0.36–0ubuntu0.20.04.1 for Linux on x86_64 ((Ubuntu))


# Download file
root@dev01:/opt/fineract$ wget https://downloads.mysql.com/archives/get/p/3/file/mysql-connector-j_8.0.33-1ubuntu20.04_all.deb

# Install downloaded deb pkg
root@dev01:/opt/fineract$ dpkg -i mysql-connector-j_8.0.33–1ubuntu20.04_all.deb
Selecting previously unselected package mysql-connector-j.
(Reading database … 125746 files and directories currently installed.)
Preparing to unpack mysql-connector-j_8.0.33–1ubuntu20.04_all.deb …
Unpacking mysql-connector-j (8.0.33–1ubuntu20.04) …
Setting up mysql-connector-j (8.0.33–1ubuntu20.04) …

Now the jar will be available in the path:

/usr/share/java/mysql-connector-j-8.0.33.jar

Build Fineract from Codebase

Download codebase

Refer link — https://github.com/apache/fineract/

root@dev01:git clone https://github.com/apache/fineract.git
….

# Switch to latest “Tag” version
# NOTE: code is tagged and not in branch 
root@dev01:/opt/fineract$ git checkout tags/1.10
Note: switching to 'tags/1.10'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -c with the switch command. Example:

  git switch -c <new-branch-name>

Or undo this operation with:

  git switch -

Turn off this advice by setting config variable advice.detachedHead to false

HEAD is now at fe85677d6 FINERACT-1971: Fix loan cob parameter name

root@dev01:/opt/fineract$ 

root@dev01:/opt/fineract$ git branch
* (HEAD detached at 1.10)
  develop
root@dev01:/opt/fineract$

Configure DB configurations

First get hands on — DB User, DB pass and DB timezone

Find DB timezone as -

sudo mysql -u fineract -p
mysql> SELECT @@system_time_zone;
+ - - - - - - - - - - +
| @@system_time_zone |
+ - - - - - - - - - - +
| UTC |
+ - - - - - - - - - - +
1 row in set (0.02 sec)
mysql> exit

Configure these properties

root@dev01:/opt/fineract$ vi ./fineract-provider/src/main/resources/application.properties
fineract.tenant.username=${FINERACT_DEFAULT_TENANTDB_UID:fineract}
fineract.tenant.password=${FINERACT_DEFAULT_TENANTDB_PWD:fineract011}
…
fineract.tenant.timezone=${FINERACT_DEFAULT_TENANTDB_TIMEZONE:UTC}
…
spring.datasource.hikari.username=${FINERACT_HIKARI_USERNAME:fineract}
spring.datasource.hikari.password=${FINERACT_HIKARI_PASSWORD:fineract011}
spring.datasource.hikari.driverClassName=${FINERACT_HIKARI_DRIVER_SOURCE_CLASS_NAME:com.mysql.cj.jdbc.Driver}

(Option #1) Build Fineract as Jar

NOTE: This build is applicable if you want to do the build as a Jar and host as a Microservice and start only the fineract backend. Its important to understand that Fineract doesn’t have a UI (Refer fineract > faqs).

Follow steps to build fineract as a war -

  • If you want to have MIFOS demo downloaded and host fineract in a tomcat, follow Build Fineract with UI below. This is best suited for a Demo
  • If you want to host the software as a solution, then its recommended that backend is deployed separately (different VM) from the front end. In which case, you could follow the steps in this section to build / deploy the code as a jar.
root@dev01:/opt/fineract$./gradlew clean bootJar

# Many warnings, mostly java version compatibility specific
# For more on this, please refer to https://docs.gradle.org/8.6/userguide/command_line_interface.html#sec:command_line_warnings in the Gradle documentation.

BUILD SUCCESSFUL in 2m 47s
77 actionable tasks: 67 executed, 8 from cache, 2 up-to-date

root@dev01:/opt/fineract$
# Final build location
fineract-provider/build/libs

root@dev01:/opt/fineract$ ls fineract-provider/build/libs
fineract-provider-1.10.0-SNAPSHOT.jar

NOTE: Observation : If it doesn’t get built the first time, due to property errors etc, then its worth checking out the code again and rebuilding, rather than fixing the build

(Option #2) Build Fineract as war with MIFOS demo

NOTE: This build is applicable if you want to do the build as a Jar and host as a Microservice and start only the fineract backend. Its important to understand that Fineract doesn’t have a UI (Refer fineract > faqs).

Follow steps to build fineract as a war -

  • If you want to have MIFOS demo downloaded and host fineract in a tomcat, follow Build Fineract with UI below. This is best suited for a Demo
  • If you want to host the software as a solution, then its recommended that backend is deployed separately (different VM) from the front end. In which case, you could follow the steps in this section to build / deploy the code as a jar.
root@dev01:/opt/fineract$ ./gradlew :fineract-war:clean :fineract-war:war
…
# Final build location
fineract-war/build/libs
root@dev01:/opt/fineract/fineract-war/build/libs# ll
total 172084
drwxr-xr-x 2 root root 4096 Apr 24 13:28 ./
drwxr-xr-x 4 root root 4096 Apr 24 13:28 ../
-rw-r - r - 1 root root 176200435 Apr 24 13:28 fineract-provider.war
root@dev01:/opt/fineract/fineract-war/build/libs#

Download MIFOS

Download mifos UI from — https://mifos.org/take-action/get-mifos/

Which should download a file of name format —

mifosplatform-23.12.31.RELEASE.zip

Unzip this file inside Tomcat/webapps

Starting Fineract

(Option #1) Starting Fineract as a Jar file

Use these instructions if the build was as Jar (option #1) above

root@dev01:/opt/fineract$ java -Dloader.path=/usr/share/java -jar ./fineract-provider/build/libs/fineract-provider-1.10.0-SNAPSHOT.jar
- -
_ _ _____ _ _
/ \ _ __ __ _ ___| |__ ___ | ___(_)_ __ ___ _ __ __ _ ___| |_
/ _ \ | '_ \ / _` |/ __| '_ \ / _ \ | |_ | | '_ \ / _ \ '__/ _` |/ __| __|
/ ___ \| |_) | (_| | (__| | | | __/ | _| | | | | | __/ | | (_| | (__| |_
/_/ \_\ .__/ \__,_|\___|_| |_|\___| |_| |_|_| |_|\___|_| \__,_|\___|\__|
|_|
© 2015–2024 Apache Fineract (https://fineract.apache.org)
Powered by Spring Boot 3.2.2
2024–04–24 09:34:01.924 - INFO 27469 - - [
….
2024–04–24 09:34:25.915 - INFO 27469 - - [ main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat initialized with port 8443 (https)
2024–04–24 09:34:25.984 - INFO 27469 - - [ main] o.apache.catalina.core.StandardService : Starting service [Tomcat]
2024–04–24 09:34:25.985 - INFO 27469 - - [ main] o.apache.catalina.core.StandardEngine : Starting Servlet engine: [Apache Tomcat/10.1.18]
2024–04–24 09:34:26.149 - INFO 27469 - - [ main] o.a.c.c.C.[.[.[/fineract-provider] : Initializing Spring embedded WebApplicationContext
- -

Create a Startup script

root@dev01:/opt/fineract/# mkdir bin
root@dev01:/opt/fineract/# mkdir logs
root@dev01:/opt/fineract/# cd bin
# Create a script as below and assign execute permissions
root@dev01:/opt/fineract/bin# cat startupFineract.sh
#! /bin/bash
export FINERACT_HOME=/opt/fineract
nohup java -Dloader.path=/usr/share/java -jar ${FINERACT_HOME}/fineract-provider/build/libs/fineract-provider-1.10.0-SNAPSHOT.jar > ../logs/fineract.log &
root@dev01:/opt/fineract/bin#

(Option #2) Starting Fineract as a war file with/ MIFOS UI

Configuring Tomcat for Fineract War and MIFOS

  • Unzip tomcat
  • Rename webapps
  • Create a new empty webapps folder
root@dev01:/opt/apache-tomcat-10.1.23# ll
total 164
drwxr-xr-x 10 root root 4096 Apr 24 12:54 ./
drwxr-xr-x 8 root root 4096 Apr 24 13:26 ../
drwxr-x - - 2 root root 4096 Apr 25 13:18 bin/
-rw-r - - - 1 root root 21043 Apr 16 12:17 BUILDING.txt
drwx - - - 3 root root 4096 Apr 24 15:09 conf/
-rw-r - - - 1 root root 6210 Apr 16 12:17 CONTRIBUTING.md
drwxr-x - - 2 root root 4096 Apr 24 13:33 lib/
-rw-r - - - 1 root root 60393 Apr 16 12:17 LICENSE
drwxr-x - - 2 root root 4096 Apr 25 13:03 logs/
-rw-r - - - 1 root root 2333 Apr 16 12:17 NOTICE
-rw-r - - - 1 root root 3298 Apr 16 12:17 README.md
-rw-r - - - 1 root root 6776 Apr 16 12:17 RELEASE-NOTES
-rw-r - - - 1 root root 16076 Apr 16 12:17 RUNNING.txt
drwxr-x - - 2 root root 4096 Apr 25 13:35 temp/
drwxr-xr-x 4 root root 4096 Apr 24 13:31 webapps/
drwxr-x - - 7 root root 4096 Apr 16 12:17 webapps_orig/
drwxr-x - - 3 root root 4096 Apr 24 13:19 work/
root@dev01:/opt/apache-tomcat-10.1.23#

Configure MIFOS

  • Copy contents of mifosplatform-23.12.31.RELEASE/webapps/* to tomcat/webapps/ROOT/ path
  • Configure “env.js” with right URLs
root@dev01:/opt/apache-tomcat-10.1.23/webapps/ROOT/assets# ls -l
total 28
-rw-r - r - 1 root root 916 Apr 25 13:30 env.js
-rw-r - r - 1 root root 884 Apr 24 12:59 env.js.orig
-rw-r - r - 1 root root 996 Apr 24 12:55 env.template.js
drwxr-xr-x 2 root root 4096 Apr 24 12:55 images
drwxr-xr-x 2 root root 4096 Apr 24 12:55 mock
drwxr-xr-x 2 root root 4096 Apr 24 12:55 styles
drwxr-xr-x 2 root root 4096 Apr 24 12:55 translations
root@dev01:/opt/apache-tomcat-10.1.23/webapps/ROOT/assets#
  • Configure “env.js” with right URLs
root@dev01:/opt/apache-tomcat-10.1.23/webapps/ROOT/assets# more env.js
(function(window) {
window["env"] = window["env"] || {};
// BackEnd Environment variables
window["env"]["fineractApiUrls"] = 'https://localhost:8080';
window["env"]["fineractApiUrl"] = 'https://localhost:8080';
window["env"]["apiProvider"] = '/fineract-provider/api';
window["env"]["apiVersion"] = '/v1';
window["env"]["fineractPlatformTenantId"] = 'default';

Setup Fineract War

Copy Fineract war from Option#2 above

root@dev01:/opt/apache-tomcat-10.1.23/webapps# ll
total 172092
drwxr-xr-x 4 root root 4096 Apr 24 13:31 ./
drwxr-xr-x 10 root root 4096 Apr 24 12:54 ../
drwxr-x - - 4 root root 4096 Apr 24 13:31 fineract-provider/
-rw-r - r - 1 root root 176200435 Apr 24 13:29 fineract-provider.war
drwxr-xr-x 3 root root 4096 Apr 24 12:55 ROOT/
root@dev01:/opt/apache-tomcat-10.1.23/webapps#

Finally Start the tomcat !!

Final State

APIs should be visible from URL : https://localhost:8080/fineract-provider/swagger-ui/index.html

If MIFOS UI is also setup, then it should be accessible as — http://localhost:8080/

Bian
Apache Fineract
Installation

--

--

D Kuruppath

Written by D Kuruppath

12 Followers

Passioniate Deep Tech bunch — focussing on Infra, DevOps, Microservices, Cloud and Integration. Connect with us for our services.

Help

Status

About

Careers

Press

Blog

Privacy

Terms

Text to speech

Teams