Fineract is a mature platform with open APIs that provides a reliable, robust, and affordable core banking solution for financial institutions offering services to the world’s 2 billion underbanked and unbanked.
Have a look at the FAQ on our Wiki at apache.org if this README does not answer what you are looking for.
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, and just send us a friendly "Hello!" introduction email; we're a friendly bunch, and look forward to hearing from you.
- Java >= 1.8 (Oracle JVMs have been tested)
- MySQL 5.5
You can run the required version of the database server in a container, instead of having to install it, like this:
docker run --name mysql-5.5 -p 3306:3306 -e MYSQL_ROOT_PASSWORD=mysql -d mysql:5.5
and stop and destroy it like this:
docker rm -f mysql-5.5
Beware that this database container database keeps its state inside the container and not on the host filesystem. It is lost when you destroy (rm) this container. This is typically fine for development. See Caveats: Where to Store Data on the database container documentation re. how to make it persistent instead of ephemeral.
Run the following commands:
./gradlew createDB -PdbName=fineract_tenants./gradlew createDB -PdbName=fineract_default./gradlew tomcatRunWAR
The file fineract-provider/gradle/wrapper/gradle-wrapper.jar binary is checked into this projects Git source repository, but won't exist in your copy of the Fineract codebase if you downloaded a released source archive from apache.org. In that case, you need to download it using the commands below:
wget --no-check-certificate -P fineract-provider/gradle/wrapper https://github.com/apache/fineract/raw/develop/fineract-provider/gradle/wrapper/gradle-wrapper.jar
(or)
curl --insecure -L https://github.com/apache/fineract/raw/develop/fineract-provider/gradle/wrapper/gradle-wrapper.jar > fineract-provider/gradle/wrapper/gradle-wrapper.jar
- Extract the archive file to your local directory.
- Run
./gradlew rat. A report will be generated under build/reports/rat/rat-report.txt
- Extract the archive file to your local directory.
- Run
./gradlew clean waror./gradlew buildto build a deployable war file which will be created at build/libs directory.
Note that if this is the first time to access MySQL DB, then you may need to reset your password.
Run the following commands, very similarly to how .travis.yml does:
./gradlew createDB -PdbName=fineract_tenants./gradlew createDB -PdbName=fineract_default./gradlew clean integrationTest
It is possible to do a 'one-touch' installation of Fineract using containers (AKA "Docker").
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.
Now to run a new Fineract instance you can simply:
git clone https://github.com/apache/fineract.git ; cd fineractdocker-compose builddocker-compose up -d- Fineract will run at https://localhost:8443/fineract-provider now!
The docker-compose.yml will build the fineract container from the source based on the Dockerfile.
https://hub.docker.com/r/apache/fineract has a pre-built container 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.
(Note that in previous versions, the mysqlserver environment variable used at docker build time instead of at
docker run time did something similar; this has changed in FINERACT-773),
and the mysqlserver environment variable is now no longer supported.)
You can also run Fineract using containers on a Kubernetes cluster.
Make sure you set up and connect to your Kubernetes cluster.
You can follow this guide to set up a Kubernetes cluster on GKE. Make sure to replace apache-fineract-cn with apache-fineract
Now e.g. from your Google Cloud shell, run the following commands:
git clone https://github.com/apache/fineract.git ; cd fineract/kubernetes./kubectl-startup
To shutdown and reset your Cluster, run:
./kubectl-shutdown
Alternatively, you can run fineract on a local kubernetes cluster using minikube.
As Prerequisites, you must have minikube and kubectl installed on your machine; see
Minikube & Kubectl install.
Now to run a new Fineract instance on Minikube you can simply:
-
git clone https://github.com/apache/fineract.git ; cd fineract/kubernetes -
minikube start -
./kubectl-startup.sh -
minikube service fineract-server --url --https -
Fineract is now running at the printed URL (note HTTP), which you can check e.g. using:
http --verify=no --timeout 240 --check-status get $(minikube service fineract-server --url --https)/fineract-provider/actuator/health
To check the status of your containers on your local minikube Kubernetes cluster, run:
minikube dashboard
You can check Fineract logs using:
kubectl logs deployment/fineract-server
To shutdown and reset your cluster, run:
./kubectl-shutdown
We have some open issues in JIRA with Kubernetes related enhancement ideas which you are welcome to contribute to.
This project enforces its code conventions using checkstyle.xml. It is configured to run automatically during the normal Gradle build, and fail if there are any style violations detected. We recommend that you configure your favourite Java IDE to match those conventions. For Eclipse, you can File > Import > General > Preferences our config/fineractdev-eclipse-preferences.epf. You could also use Checkstyle directly in your IDE (but you don't neccesarily have to, it may just be more convenient for you). For Eclipse, use https://checkstyle.org/eclipse-cs/ and load our checkstyle.xml into it, for IntelliJ you can use CheckStyle-IDEA.
The project uses Jacoco to measure unit tests code coverage, to generate a report run the following command:
`./gradlew clean build jacocoTestReport`
Generated reports can be found in build/code-coverage directory.
The latest stable release can be viewed on the develop branch: Latest Release on Develop.
The progress of this project can be viewed here: View change log
This project is licensed under Apache License Version 2.0. See https://github.com/apache/incubator-fineract/blob/develop/LICENSE.md for reference.
The Connector/J JDBC Driver client library from MariaDB.org, which is licensed under the LGPL, is used in development when running integration tests that use the Flyway library. That JDBC driver is however not included in and distributed with the Fineract product and is not required to use the product. If you are developer and object to using the LGPL licensed Connector/J JDBC driver, simply do not run the integration tests that use the Flyway library. As discussed in LEGAL-462, this project therefore complies with the Apache Software Foundation third-party license policy.
The API for the Fineract-platform (project named 'Apache Fineract') is documented in the API-docs under Full API Matrix and can be viewed here.
For this demo, a demo account is also provided for users to experience the functionality of this Community App. Users can use "mifos" for USERNAME and "password" for PASSWORD(without quotation marks).
Please see https://cwiki.apache.org/confluence/display/FINERACT/Contributor%27s+Zone for the developers wiki page.
Please refer to https://cwiki.apache.org/confluence/display/FINERACT/Fineract+101 for the first-time contribution to this project.
Please see https://cwiki.apache.org/confluence/display/FINERACT/How-to+articles for technical details to get started.
Please visit https://issues.apache.org/jira/projects/FINERACT/ to open or find issues.
Project Release Roadmap on JIRA (Detailed View)
Apache Fineract / Mifos X Demo (November 2016) - https://www.youtube.com/watch?v=h61g9TptMBo
Becoming a Committer documents the process through which you can become a committer in this project.
Pull Request Size Limit documents that we cannot accept huge "code dump" Pull Requests, with some related suggestions.
How to Release Apache Fineract documents the process how we make the source code that is available here in this git repository into a binary release ZIP available on http://fineract.apache.org.
More details of the project can be found at https://cwiki.apache.org/confluence/display/FINERACT.