Apache Fineract

Apache Fineract is an open-source core banking platform providing a flexible, extensible foundation for a wide range of financial services. By making robust banking technology openly available, it lowers barriers for institutions and innovators to reach underserved and unbanked populations.

Have a look at the documentation, the wiki or at the FAQ, if this README does not answer what you are looking for.

COMMUNITY

If you are interested in contributing to this project, but perhaps don't quite know how and where to get started, please join our developer mailing list, listen into our conversations, chime into threads, or just send us a "Hello!" introduction email; we're a friendly bunch, and look forward to hearing from you. A more informal alternative is the Fineract Slack channel (thank you, Mifos, for supporting the Slack channel!).

For the developer wiki, see Contributor's Zone. Maybe these how-to articles help you to get started.

In any case visit our JIRA Dashboard to find issues to work on, see what others are doing, or open new issues.

In the moment you get started writing code, please consult our CONTRIBUTING guidelines, where you will find more information on subjects like coding style, testing and pull requests.

REQUIREMENTS

min. 16GB RAM and 8 core CPU
MariaDB >= 12.2 or PostgreSQL >= 18.0
Java >= 21 (Azul Zulu JVM is tested by our CI on GitHub Actions)

Tomcat (min. v10) is only required, if you wish to deploy the Fineract WAR to a separate external servlet container. You do not need to install Tomcat to run Fineract. We recommend the use of the self-contained JAR, which transparently embeds a servlet container using Spring Boot.

SECURITY

For a list of known vulnerabilities, see Apache Fineract Security Reports.

If you believe you have found a new vulnerability, let us know privately.

For details about security during development and deployment, see the documentation here.

INSTRUCTIONS

The following how-to's assume you have Java installed, you cloned the repository (or downloaded and extracted a specific version) and you have a database server (MariaDB or PostgreSQL) running.

Quick Start

This section provides a simplified overview of the setup process. More detailed instructions are available below.

Follow these steps to quickly set up and run Apache Fineract locally:

Prerequisites

Java 21 or higher
PostgreSQL or MariaDB running locally

Clone the repository

git clone https://github.com/apache/fineract.git
cd fineract

Create databases

./gradlew createDB -PdbName=fineract_tenants
./gradlew createDB -PdbName=fineract_default

Run the application

./gradlew devRun

Verify the application is running

curl --insecure https://localhost:8443/fineract-provider/actuator/health

How to run for local development

Run the following commands in this order:

./gradlew createDB -PdbName=fineract_tenants
./gradlew createDB -PdbName=fineract_default
./gradlew devRun

This creates two databases and builds and runs Fineract, which will be listening for API requests on port 8443 (by default) now.

Confirm Fineract is ready with, for example:

curl --insecure https://localhost:8443/fineract-provider/actuator/health

To test authenticated endpoints, include credentials in your request:

curl --location \
  https://localhost:8443/fineract-provider/api/v1/clients \
  --header 'Content-Type: application/json' \
  --header 'Fineract-Platform-TenantId: default' \
  --header 'Authorization: Basic bWlmb3M6cGFzc3dvcmQ='

How to run for production

Running Fineract to try it out is relatively easy. If you intend to use it in a production environment, be aware that a proper deployment can be complex, costly, and time-consuming. Considerations include: Security, privacy, compliance, performance, service availability, backups, and more. The Fineract project does not provide a comprehensive guide for deploying Fineract in production. You might need skills in enterprise Java applications and more. Alternatively, you could pay a vendor for Fineract deployment and maintenance. You will find tips and tricks for deploying and securing Fineract in our official documentation and in the community-maintained wiki.

How to build the JAR file

Build a modern, cloud native, fully self contained JAR file:

./gradlew clean bootJar

The JAR will be created in the fineract-provider/build/libs directory. As we are not allowed to include a JDBC driver in the built JAR, download a JDBC driver of your choice. For example:

wget https://dlm.mariadb.com/4174416/Connectors/java/connector-java-3.5.2/mariadb-java-client-3.5.2.jar

Start the JAR and specify the directory containing the JDBC driver using the loader.path option, for example:

java -Dloader.path=. -jar fineract-provider/build/libs/fineract-provider.jar

This does not require an external Tomcat.

The tenants database connection details are configured via environment variables (as with Docker container), e.g. like this:

export FINERACT_HIKARI_PASSWORD=verysecret
...
java -jar fineract-provider.jar

How to build the WAR file

Build a traditional WAR file:

./gradlew :fineract-war:clean :fineract-war:war

The WAR will be created in the fineract-war/build/libs directory. Afterwards deploy the WAR to your Tomcat Servlet Container.

We recommend using the JAR instead of the WAR file deployment, because it's much easier.

How to run using Docker or Podman

It is possible to do a 'one-touch' installation of Fineract using containers (AKA "Docker"). This includes the database running in the container.

As prerequisites, you must have docker and docker-compose installed on your machine; see Docker Install and Docker Compose Install.

Alternatively, you can also use Podman (e.g. via dnf install podman-docker), and Podman Compose (e.g. via pip3 install podman-compose) instead of Docker.

To run a new Fineract instance on Linux you can simply:

git clone https://github.com/apache/fineract.git
cd fineract
./gradlew :fineract-provider:jibDockerBuild -x test

On Windows, do this instead:

git clone https://github.com/apache/fineract.git --config core.autocrlf=input
cd fineract
gradlew :fineract-provider:jibDockerBuild -x test

Install the Loki log driver and start:

docker plugin install grafana/loki-docker-driver:latest \
  --alias loki --grant-all-permissions
docker compose -f docker-compose-development.yml up -d

The Fineract (back-end) should be running at https://localhost:8443/fineract-provider/ now. Wait for https://localhost:8443/fineract-provider/actuator/health to return {"status":"UP"}. You must go to https://localhost:8443 and remember to accept the self-signed SSL certificate of the API once in your browser.

Docker Hub has a pre-built container image of this project, built continuously.

You must specify the MySQL tenants database JDBC URL by passing it to the fineract container via environment variables; please consult the docker-compose.yml for exact details how to specify those.

The logfiles and the Java Flight Recorder output are available in PROJECT_ROOT/build/fineract/logs. If you use IntelliJ then you can double-click on the .jfr file and open it with the IDE. You can also download Azul Mission Control to analyze the Java Flight Recorder file.

NOTE: If you have issues with the file permissions and Docker Compose then you might need to change the variable values for FINERACT_USER and FINERACT_GROUP in `PROJECT_ROOT/c

Fineract

Install / Use

README