{"id":13545033,"url":"https://github.com/apache/fineract","last_synced_at":"2025-05-13T21:04:10.213Z","repository":{"id":37734631,"uuid":"48418599","full_name":"apache/fineract","owner":"apache","description":"Apache Fineract","archived":false,"fork":false,"pushed_at":"2025-04-25T14:36:57.000Z","size":87866,"stargazers_count":1558,"open_issues_count":27,"forks_count":1852,"subscribers_count":119,"default_branch":"develop","last_synced_at":"2025-04-28T12:09:22.585Z","etag":null,"topics":["apache","banking","finance","fintech","group-lending","group-savings","java","lending","loans","microfinance","savings","social-impact","tech4good"],"latest_commit_sha":null,"homepage":"https://fineract.apache.org","language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apache.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE_RELEASE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-12-22T08:00:06.000Z","updated_at":"2025-04-27T23:59:21.000Z","dependencies_parsed_at":"2025-04-09T19:10:06.022Z","dependency_job_id":"b63903d9-964e-4988-8921-20a531fe705d","html_url":"https://github.com/apache/fineract","commit_stats":{"total_commits":6406,"total_committers":259,"mean_commits":"24.733590733590734","dds":0.8582578832344677,"last_synced_commit":"717eb69425be0652e685ed6a861e26e7d261d804"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Ffineract","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Ffineract/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Ffineract/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Ffineract/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apache","download_url":"https://codeload.github.com/apache/fineract/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251311331,"owners_count":21569009,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apache","banking","finance","fintech","group-lending","group-savings","java","lending","loans","microfinance","savings","social-impact","tech4good"],"created_at":"2024-08-01T11:00:56.869Z","updated_at":"2025-04-28T12:09:35.615Z","avatar_url":"https://github.com/apache.png","language":"Java","readme":"Apache Fineract: A Platform for Microfinance\n============\n\u003c!-- TODO Reactivate when there is a working CI-CD instance: [![Swagger Validation](https://validator.swagger.io/validator?url=https://sandbox.mifos.community/fineract-provider/swagger-ui/fineract.yaml)](https://validator.swagger.io/validator/debug?url=https://sandbox.mifos.community/fineract-provider/swagger-ui/fineract.yaml) --\u003e\n[![Build](https://github.com/apache/fineract/actions/workflows/build-mariadb.yml/badge.svg?branch=develop)](https://github.com/apache/fineract/actions/workflows/build-mariadb.yml)\n[![Docker Hub](https://img.shields.io/docker/pulls/apache/fineract.svg?logo=Docker)](https://hub.docker.com/r/apache/fineract)\n[![Docker Build](https://github.com/apache/fineract/actions/workflows/publish-dockerhub.yml/badge.svg)](https://github.com/apache/fineract/actions/workflows/publish-dockerhub.yml)\n[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=apache_fineract\u0026metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=apache_fineract)\n\n\u003c/b\u003e\n\nFineract 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 3 billion underbanked and unbanked.\n\n[Have a look at the FAQ on our Wiki at apache.org](https://cwiki.apache.org/confluence/display/FINERACT/FAQ) if this README does not answer what you are looking for.  [Visit our JIRA Dashboard](https://issues.apache.org/jira/secure/Dashboard.jspa?selectPageId=12335824) to find issues to work on, see what others are working on, or open new issues.\n\nCOMMUNITY\n=========\n\nIf 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](http://fineract.apache.org/#contribute), listen into our conversations, chime into threads, and just send us a \"Hello!\" introduction email; we're a friendly bunch, and look forward to hearing from you.\n\n\nREQUIREMENTS\n============\n* `Java \u003e= 21` (Azul Zulu JVM is tested by our CI on GitHub Actions)\n* MariaDB `11.5.2`\n\nYou can run the required version of the database server in a container, instead of having to install it, like this:\n\n    docker run --name mariadb-11.5 -p 3306:3306 -e MARIADB_ROOT_PASSWORD=mysql -d mariadb:11.5.2\n\nand stop and destroy it like this:\n\n    docker rm -f mariadb-11.5\n\n\u003cbr\u003eBeware 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](https://hub.docker.com/_/mariadb) re. how to make it persistent instead of ephemeral.\u003cbr\u003e\n\nTomcat v10 is only required if you wish to deploy the Fineract WAR to a separate external servlet container.  Note that you do not require to install Tomcat to develop Fineract, or to run it in production if you use the self-contained JAR, which transparently embeds a servlet container using Spring Boot.  (Until FINERACT-730, Tomcat 7/8 were also supported, but now Tomcat 10 is required.)\n\n\u003cbr\u003eIMPORTANT: If you use MySQL or MariaDB\n============\n\nRecently (after release `1.7.0`), we introduced improved date time handling in Fineract. Date time is from now on stored in UTC and we are enforcing UTC timezone even on the JDBC driver, e. g. for MySQL:\n\n```\nserverTimezone=UTC\u0026useLegacyDatetimeCode=false\u0026sessionVariables=time_zone=‘-00:00’\n```\n\n__DO__: If you do use MySQL as your Fineract database then the following configuration is highly recommended:\n\n* Run the application in UTC (the default command line in our Docker image has the necessary parameters already set)\n* Run the MySQL database server in UTC (if you use managed services like AWS RDS then this should be the default anyway, but it would be good to double-check)\n\n__DON'T__: In case the Fineract instance and the MySQL server are __not__ running in UTC then the following could happen:\n\n* MySQL is saving date time values differently from PostgreSQL\n* Example scenario: if the Fineract instance runs in timezone: GMT+2, and the local date time is 2022-08-11 17:15 ...\n* ... then __PostgreSQL saves__ the LocalDateTime as is: __2022-08-11 17:15__\n* ... and __MySQL saves__ the LocalDateTime in UTC: __2022-08-11 15:15__\n* ... but when we __read__ the date time from PostgreSQL __or__ from MySQL, then both systems give us the same values: __2022-08-11 17:15 GMT+2__\n\nIf a previously used Fineract instance didn't run in UTC (backward compatibility), then all prior dates will be read wrongly by MySQL/MariaDB. This can cause issues when you run the database migration scripts.\n\n__RECOMMENDATION__: you need to shift all dates in your database by the timezone offset that your Fineract instance used.\n\n\u003cbr\u003eINSTRUCTIONS: How to run for local development\n============\n\nRun the following commands:\n1. `./gradlew createDB -PdbName=fineract_tenants`\n1. `./gradlew createDB -PdbName=fineract_default`\n1. `./gradlew devRun`\n\n\n\u003cbr\u003eINSTRUCTIONS: How to build the JAR file\n============\n1. Clone the repository or download and extract the archive file to your local directory.\n2. Run `./gradlew clean bootJar` to build a modern cloud native fully self contained JAR file which will be created at `fineract-provider/build/libs` directory.\n3. 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`\n4. Start the jar and pass the directory where you have downloaded the JDBC driver as loader.path, for example: `java -Dloader.path=. -jar fineract-provider/build/libs/fineract-provider.jar` (does not require external Tomcat)\n\nThe tenants database connection details are configured [via environment variables (as with Docker container)](#instructions-to-run-using-docker-and-docker-compose), e.g. like this:\n\n    export FINERACT_HIKARI_PASSWORD=verysecret\n    ...\n    java -jar fineract-provider.jar\n\n\n\u003cbr\u003eSECURITY\n============\nNOTE: The HTTP Basic and OAuth2 authentication schemes are mutually exclusive. You can't enable them both at the same time. Fineract checks these settings on startup and will fail if more than one authentication scheme is enabled.\n\nHTTP Basic Authentication\n------------\nBy default Fineract is configured with a HTTP Basic Authentication scheme, so you actually don't have to do anything if you want to use it. But if you would like to explicitly choose this authentication scheme then there are two ways to enable it:\n1. Use environment variables (best choice if you run with Docker Compose):\n```\nFINERACT_SECURITY_BASICAUTH_ENABLED=true\nFINERACT_SECURITY_OAUTH_ENABLED=false\n```\n2. Use JVM parameters (best choice if you run the Spring Boot JAR):\n```\njava -Dfineract.security.basicauth.enabled=true -Dfineract.security.oauth.enabled=false -jar fineract-provider.jar\n```\n\n\u003cbr\u003eOAuth2 AUTHENTICATION\n------------\nThere is also an OAuth2 authentication scheme available. Again, two ways to enable it:\n1. Use environment variables (best choice if you run with Docker Compose):\n```\nFINERACT_SECURITY_BASICAUTH_ENABLED=false\nFINERACT_SECURITY_OAUTH_ENABLED=true\n```\n2. Use JVM parameters (best choice if you run the Spring Boot JAR):\n```\njava -Dfineract.security.basicauth.enabled=false -Dfineract.security.oauth.enabled=true -jar fineract-provider.jar\n```\n\nTWO FACTOR AUTHENTICATION (2FA)\n------------\nYou can also enable 2FA authentication. Depending on how you start Fineract add the following:\n\n1. Use environment variable (best choice if you run with Docker Compose):\n```\nFINERACT_SECURITY_2FA_ENABLED=true\n```\n2. Use JVM parameter (best choice if you run the Spring Boot JAR):\n```\n-Dfineract.security.2fa.enabled=true\n```\n\n\n\u003cbr\u003eINSTRUCTIONS: How to build a WAR file\n============\n1. Clone the repository or download and extract the archive file to your local directory.\n2. Run `./gradlew :fineract-war:clean :fineract-war:war` to build a traditional WAR file which will be created at `fineract-war/build/libs` directory.\n3. Deploy this WAR to your Tomcat v10 Servlet Container.\n\nWe recommend using the JAR instead of the WAR file deployment, because it's much easier.\n\nNote that with the 1.4 release the tenants database pool configuration changed from Tomcat DBCP in XML to an embedded Hikari, configured by environment variables, see above.\n\n\nINSTRUCTIONS: How to run tests\n============\n\nUnit tests\n----------\n\nHere's how to run the set of relatviely fast and indepedent Fineract tests:\n\n```bash\n./gradlew test -x :twofactor-tests:test -x :oauth2-tests:test -x :integration-tests:test\n```\n\nThis runs nearly 1,000 tests and completes in a few minutes on decent hardware.\nThey shouldn't need any special servers/services running.\n\nIntegration tests\n-----------------\n\nRunning tests with external dependencies yourself is a multi-step process with many moving parts.\nSometimes there are arbitrary failures and the prerequisite setup can be daunting.\nA full local integration test run (on a developer workstation) covering every possible test using every external service and every supported relational database engine could take an entire day, and that's assuming everything is properly configured and runs as expected.\n\nRight now we depend on GitHub to know if \"the build\" is passing (it's actually multiple builds).\nThe authoritative source of truth for what commands/services/tests to run, how, and when are the files in `.github/workflows/`.\nOutput from runs based on those configuration files appears at \u003chttps://github.com/apache/fineract/actions\u003e.\n\nIncorrect default Java-related executables may cause test failures.\nTo fix this on Debian and Ubuntu systems, run the following:\n\n```bash\nexport JAVA_HOME=/usr/lib/jvm/zulu21\nsudo update-alternatives --set java $JAVA_HOME/bin/java\nsudo update-alternatives --set javac $JAVA_HOME/bin/javac\nsudo update-alternatives --set javadoc $JAVA_HOME/bin/javadoc\n```\n\nThis would correct, for example, a [class file verson error](https://en.wikipedia.org/wiki/Java_class_file#General_layout).\nYou might see something like this if a Java 11 executable (class file format version 56) was the system default, but the integration tests were using Java 21 (class file format version 65):\n\n```\nUnsupportedClassVersionError: com.example.package/ClassName has been compiled by a more recent version of the Java Runtime (class file version 65.0), this version of the Java Runtime only recognizes class file versions up to 55.0\n```\n\nThese builds are run in [short-lived virtual machines](https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners), so locally reproducing the same may require additional effort, such as these extra clean-up procedures:\n\n```bash\n# Destroy anything untracked by git.\n# ⚠️ This may delete something important, e.g. a finely-tuned IDE configuration.\ngit clean --force -dx\n\n# Destroy various caches and configs.\n# ⚠️ This may delete gibibytes of cached data, making the next build very slow.\nrm -rf ~/.gradle ~/.m2 /tmp/cargo*\n\n# Destroy any Java containers left running.\n# 💚 This is generally very safe to run between builds.\nps auxwww | grep [c]argo | awk '{ print $2 }' | xargs -r kill\n```\n\nIntegration test runs such as `./gradlew --no-daemon --console=plain test -x :twofactor-tests:test -x :oauth2-test:test :fineract-e2e-tests-runner:test -PdbType=postgresql` in `.github/workflows/build-postgresql.yml` often take an hour or longer to complete.\nIf you notice the `:integration-tests:test` task taking significantly less time, say, one minute, gradle may be skipping it.\nLook for something like this in the test output:\n\n```\n\u003e Task :integration-tests:test UP-TO-DATE 👀\nCustom actions are attached to task ':integration-tests:test'.\nBuild cache key for task ':integration-tests:test' is 6aeeec3f58bf9703d4c100fbaa657f5c\nSkipping task ':integration-tests:test' as it is up-to-date.\nResolve mutations for :integration-tests:cargoStopLocal (Thread[Execution worker Thread 11,5,main]) started.\n:integration-tests:cargoStopLocal (Thread[Execution worker Thread 11,5,main]) started.\n```\n\n(This is with the `--info` gradle argument with eyeballs added for emphasis)\nThe `--rerun-tasks` gradle argument may help, or you can try destroying `~/.gradle` and other clean-up procedures as indicated above then re-running tests.\nThis is useful for repeated test runs (say, for timing) when gradle would otherwise assume a task is \"up-to-date\" and not re-run it.\n\nTesting within IDEs\n-----------------\n\nSee the next section for testing in Eclipse.\n\nSee \u003chttps://fineract-academy.com\u003e for testing in IntelliJ.\n\nINSTRUCTIONS: How to run and debug in Eclipse IDE\n============\n\nIt is possible to run Fineract in Eclipse IDE and also to debug Fineract using Eclipse's debugging facilities.\nTo do this, you need to create the Eclipse project files and import the project into an Eclipse workspace:\n\n1. Create Eclipse project files into the Fineract project by running `./gradlew cleanEclipse eclipse`\n2. Import the fineract-provider project into your Eclipse workspace (File-\u003eImport-\u003eGeneral-\u003eExisting Projects into Workspace, choose root directory fineract/fineract-provider)\n3. Do a clean build of the project in Eclipse (Project-\u003eClean...)\n3. Run / debug Fineract by right clicking on org.apache.fineract.ServerApplication class and choosing Run As / Debug As -\u003e Java Application. All normal Eclipse debugging features (breakpoints, watchpoints etc) should work as expected.\n\nIf you change the project settings (dependencies etc) in Gradle, you should redo step 1 and refresh the project in Eclipse.\n\nYou can also use Eclipse Junit support to run tests in Eclipse (Run As-\u003eJunit Test)\n\nFinally, modifying source code in Eclipse automatically triggers hot code replace to a running instance, allowing you to immediately test your changes\n\n\nINSTRUCTIONS: How to run using Docker and docker-compose\n===================================================\n\nIt is possible to do a 'one-touch' installation of Fineract using containers (AKA \"Docker\").\nFineract now packs the mifos community-app web UI in it's docker deploy.\nYou can now run and test fineract with a GUI directly from the combined docker builds.\nThis includes the database running in a container.\n\nAs Prerequisites, you must have `docker` and `docker-compose` installed on your machine; see\n[Docker Install](https://docs.docker.com/install/) and\n[Docker Compose Install](https://docs.docker.com/compose/install/).\n\nAlternatively, you can also use [Podman](https://github.com/containers/libpod)\n(e.g. via `dnf install podman-docker`), and [Podman Compose](https://github.com/containers/podman-compose/)\n(e.g. via `pip3 install podman-compose`) instead of Docker.\n\nNow to run a new Fineract instance you can simply:\n\n1. `git clone https://github.com/apache/fineract.git ; cd fineract`\n1. for windows, use `git clone https://github.com/apache/fineract.git --config core.autocrlf=input ; cd fineract`\n1. `./gradlew :fineract-provider:jibDockerBuild -x test`\n1. install the Loki log driver with `docker plugin install grafana/loki-docker-driver:latest --alias loki --grant-all-permissions`\n1. `docker compose -f docker-compose-development.yml up -d`\n1. fineract (back-end) is running at https://localhost:8443/fineract-provider/\n1. wait for https://localhost:8443/fineract-provider/actuator/health to return `{\"status\":\"UP\"}`\n1. you must go to https://localhost:8443 and remember to accept the self-signed SSL certificate of the API once in your browser, otherwise  you get a message that is rather misleading from the UI.\n1. community-app (UI) is running at http://localhost:9090/?baseApiUrl=https://localhost:8443/fineract-provider\u0026tenantIdentifier=default\n1. login using default _username_ `mifos` and _password_ `password`\n\nhttps://hub.docker.com/r/apache/fineract has a pre-built container image of this project, built continuously.\n\nYou must specify the MySQL tenants database JDBC URL by passing it to the `fineract` container via environment\nvariables; please consult the [`docker-compose.yml`](docker-compose.yml) for exact details how to specify those.\n_(Note that in previous versions, the `mysqlserver` environment variable used at `docker build` time instead of at\n`docker run` time did something similar; this has changed in [FINERACT-773](https://issues.apache.org/jira/browse/FINERACT-773)),\nand the `mysqlserver` environment variable is now no longer supported.)_\n\nThe 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 from here https://www.azul.com/products/components/azul-mission-control/ to analyze the Java Flight Recorder file.\n\nNOTE: 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/config/docker/env/fineract-common.env`. You can find out what values you need to put there with the following commands:\n\n```\nid -u ${USER}\nid -u ${GROUP}\n```\n\nPlease make sure that you are not checking in your changed values. The defaults should normally work for most people.\n\nINSTRUCTIONS: How to build documentation\n===================================================\n\nRun the following command:\n\n```bash\n./gradlew doc\n```\n\nSome dependencies are required (e.g. Ghostscript, Graphviz), see `.github/workflows/build-documentation.yml` for hints.\n\nAdditionally, IDEs such as IntelliJ are useful for editing the AsciiDoc source files while providing a live rendered preview.\n\nHTML rendered from the AsciiDoc source files is also available online at \u003chttps://fineract.apache.org/docs/current/\u003e.\n\nConnection pool configuration\n=============================\n\nPlease check `application.properties` to see which connection pool settings can be tweaked. The associated environment variables are prefixed with `FINERACT_HIKARI_*`. You can find more information about specific connection pool settings (Hikari) at https://github.com/brettwooldridge/HikariCP#configuration-knobs-baby\n\nNOTE: we'll keep backwards compatibility until one of the next releases to ensure that things are working as expected. Environment variables prefixed `fineract_tenants_*` can still be used to configure the database connection, but we strongly encourage using `FINERACT_HIKARI_*` with more options.\n\n\u003cbr\u003eSSL CONFIGURATION\n=================\n\nRead also [the HTTPS related doc](fineract-doc/src/docs/en/chapters/deployment/https.adoc).\n\nBy default SSL is enabled, but all SSL related properties are now tunable. SSL can be turned off by setting the environment variable `FINERACT_SERVER_SSL_ENABLED` to false. If you do that then please make sure to also change the server port to `8080` via the variable `FINERACT_SERVER_PORT`, just for the sake of keeping the conventions.\nYou can choose now easily a different SSL keystore by setting `FINERACT_SERVER_SSL_KEY_STORE` with a path to a different (not embedded) keystore. The password can be set via `FINERACT_SERVER_SSL_KEY_STORE_PASSWORD`. See the `application.properties` file and the latest Spring Boot documentation (https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html) for more details.\n\n\n\u003cbr\u003eTOMCAT CONFIGURATION\n====================\n\nPlease refer to the `application.properties` and the official Spring Boot documentation (https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html) on how to do performance tuning for Tomcat. Note: you can set now the acceptable form POST size (default is 2MB) via environment variable `FINERACT_SERVER_TOMCAT_MAX_HTTP_FORM_POST_SIZE`.\n\n\n\u003cbr\u003eINSTRUCTIONS: How to run on Kubernetes\n=================================\n\n\u003cbr\u003eGeneral Clusters\n----------------\n\nYou can also run Fineract using containers on a Kubernetes cluster.\nMake sure you set up and connect to your Kubernetes cluster.\nYou can follow [this](https://cwiki.apache.org/confluence/display/FINERACT/Install+and+configure+kubectl+and+Google+Cloud+SDK+on+ubuntu+16.04) guide to set up a Kubernetes cluster on GKE. Make sure to replace `apache-fineract-cn` with `apache-fineract`\n\nNow e.g. from your Google Cloud shell, run the following commands:\n\n1. `git clone https://github.com/apache/fineract.git ; cd fineract/kubernetes`\n1. `./kubectl-startup.sh`\n\nTo shutdown and reset your Cluster, run:\n\n    ./kubectl-shutdown.sh\n\nUsing Minikube\n--------------\n\nAlternatively, you can run fineract on a local kubernetes cluster using [minikube](https://minikube.sigs.k8s.io/docs/).\nAs Prerequisites, you must have `minikube` and `kubectl` installed on your machine; see\n[Minikube \u0026 Kubectl install](https://kubernetes.io/docs/tasks/tools/install-minikube/).\n\nNow to run a new Fineract instance on Minikube you can simply:\n\n1. `git clone https://github.com/apache/fineract.git ; cd fineract/kubernetes`\n1. `minikube start`\n1. `./kubectl-startup.sh`\n1. `minikube service fineract-server --url --https`\n1. Fineract is now running at the printed URL (note HTTP), which you can check e.g. using:\n\n   http --verify=no --timeout 240 --check-status get $(minikube service fineract-server --url --https)/fineract-provider/actuator/health\n\nTo check the status of your containers on your local minikube Kubernetes cluster, run:\n\n    minikube dashboard\n\nYou can check Fineract logs using:\n\n    kubectl logs deployment/fineract-server\n\nTo shutdown and reset your cluster, run:\n\n    ./kubectl-shutdown.sh\n\nTo shutdown and reset your cluster, run:\n\n    minikube ssh\n\n    sudo rm -rf /mnt/data/\n\nWe have [some open issues in JIRA with Kubernetes related enhancement ideas](https://jira.apache.org/jira/browse/FINERACT-783?jql=labels%20%3D%20kubernetes%20AND%20project%20%3D%20%22Apache%20Fineract%22%20) which you are welcome to contribute to.\n\n\nINSTRUCTIONS: How to download Gradle wrapper\n============\nThe file gradle/wrapper/gradle-wrapper.jar binary is checked into this projects Git source repository,\nbut won't exist in your copy of the Fineract codebase if you downloaded a released source archive from apache.org.\nIn that case, you need to download it using the commands below:\n\n    wget --no-check-certificate -P gradle/wrapper https://github.com/apache/fineract/raw/develop/gradle/wrapper/gradle-wrapper.jar\n\n(or)\n\n    curl --insecure -L https://github.com/apache/fineract/raw/develop/gradle/wrapper/gradle-wrapper.jar \u003e gradle/wrapper/gradle-wrapper.jar\n\n\nINSTRUCTIONS: How to run Apache RAT (Release Audit Tool)\n============\n1. Extract the archive file to your local directory.\n2. Run `./gradlew rat`. A report will be generated under build/reports/rat/rat-report.txt\n\n\nINSTRUCTIONS: How to enable External Message Broker (ActiveMQ or Apache Kafka)\n============\n\nThere are two use-cases where external message broker is needed:\n - External Business Events / Reliable Event Framework\n - Executing Partitioned Spring Batch Jobs\n\nExternal Events are business events, e.g.: `ClientCreated`, which might be important for third party systems. Apache Fineract supports ActiveMQ (or other JMS compliant brokers) and Apache Kafka endpoints for sending out Business Events. By default, they are not emitted.\n\nIn case of a large deployment with millions of accounts, the Close of Business Day Spring Batch job may run several hours. In order to speed up this task, remote partitioning of the job is supported. The Manager node partitions (breaks up) the COB job into smaller pieces (sub tasks) which then can be executed on multiple Worker nodes in parallel. The worker nodes are notified either by ActiveMQ or Kafka regarding their new sub tasks.\n### Active MQ\n\nJMS based messaging is disabled by default. In `docker-compose-postgresql-activemq.yml` an example is shown where ActiveMQ is enabled. In that configuration one Spring Batch Manager instance and two Spring Batch Worker instances are created.\nSpring based events should be disabled and jms based event handling should be enabled. Furthermore, proper broker JMS URL should be configured.\n\n```\n      FINERACT_REMOTE_JOB_MESSAGE_HANDLER_JMS_ENABLED=true\n      FINERACT_REMOTE_JOB_MESSAGE_HANDLER_SPRING_EVENTS_ENABLED=false\n      FINERACT_REMOTE_JOB_MESSAGE_HANDLER_JMS_BROKER_URL=tcp://activemq:61616\n```\n\nFor additional ActiveMQ related configuration please take a look to the `application.properties` where the supported configuration parameters are listed with their default values.\n\n### Kafka\n\nKafka support also disabled by default. In `docker-compose-postgresql-kafka.yml` an example is shown where self-hosted Kafka is enabled for both External Events and Spring Batch Remote Job execution.\n\nDuring the development Fineract was tested with PLAINTEXT Kafka brokers without authentication and with AWS MSK using IAM authentication. The extra [jar file](https://github.com/aws/aws-msk-iam-auth/releases) required for IAM authentication is already added to the classpath.\nAn example MSK setup can be found in `docker-compose-postgresql-kafka-msk.yml`.\n\nThe full list of supported Kafka related properties are documented here: https://fineract.apache.org/docs/current/\n\nCheckstyle and Spotless\n============\n\nThis project enforces its code conventions using [checkstyle.xml](config/checkstyle/checkstyle.xml) through Checkstyle and [fineract-formatting-preferences.xml](config/fineract-formatting-preferences.xml) through Spotless. They are configured to run automatically during the normal Gradle build, and fail if there are any violations detected. You can run the following command to automatically fix spotless violations:\n\n    `./gradlew spotlessApply`\n\nSince some checks are present in both Checkstyle and Spotless, the same command can help you fix some of the Checkstyle violations (but not all, other Checkstyle violations need to fixed manually).\n\nYou can also check for Spotless violations (only; but normally don't have to, because the regular build full already includes this anyway):\n\n    `./gradlew spotlessCheck`\n\nWe recommend that you configure your favourite Java IDE to match those conventions. For Eclipse, you can go to\nWindow \u003e Java \u003e Code Style and import our [config/fineractdev-formatter.xml](config/fineractdev-formatter.xml) under formatter section and [config/fineractdev-cleanup.xml](config/fineractdev-cleanup.xml) under Clean up section. The same fineractdev-formatter.xml configuration file (that can be used in Eclipse IDE) is also used by Spotless to both check for violations and autoformat code on the CLI.\nYou 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](https://plugins.jetbrains.com/plugin/1065-checkstyle-idea).\n\n\nCode Coverage Reports\n============\n\nThe project uses Jacoco to measure unit tests code coverage, to generate a report run the following command:\n\n    `./gradlew clean build jacocoTestReport`\n\nGenerated reports can be found in build/code-coverage directory.\n\n\nVersions\n============\n\nThe latest stable release can be viewed on the develop branch: [Latest Release on Develop](https://github.com/apache/fineract/tree/develop \"Latest Release\").\n\nThe progress of this project can be viewed here: [View change log](https://github.com/apache/fineract/blob/develop/CHANGELOG.md \"Latest release change log\")\n\n\nLicense\n============\n\nThis project is licensed under Apache License Version 2.0. See \u003chttps://github.com/apache/fineract/blob/develop/APACHE_LICENSETEXT.md\u003e for reference.\n\nThe Connector/J JDBC Driver client library from MariaDB.org, which is licensed under the LGPL,\nis used in development when running integration tests that use the Liquibase library.  That JDBC\ndriver is however not included in and distributed with the Fineract product and is not\nrequired to use the product.\nIf you are developer and object to using the LGPL licensed Connector/J JDBC driver,\nsimply do not run the integration tests that use the Liquibase library and/or use another JDBC driver.\nAs discussed in [LEGAL-462](https://issues.apache.org/jira/browse/LEGAL-462), this project therefore\ncomplies with the [Apache Software Foundation third-party license policy](https://www.apache.org/legal/resolved.html).\n\n\n\u003cbr\u003e\u003cbr\u003eAPACHE FINERACT PLATFORM API\n============\n\nThe API for Fineract is documented in [apiLive.htm](fineract-provider/src/main/resources/static/legacy-docs/apiLive.htm), and the [apiLive.htm can be viewed on fineract.apache.org](https://fineract.apache.org/docs/legacy/ \"API Documentation\").  If you have your own Fineract instance running, you can find this documentation under [/fineract-provider/legacy-docs/apiLive.htm](https://localhost:8443/fineract-provider/legacy-docs/apiLive.htm).\n\nThe Swagger documentation (work in progress; see [FINERACT-733](https://issues.apache.org/jira/browse/FINERACT-733)) can be accessed under [/fineract-provider/swagger-ui/index.html](https://localhost:8443/fineract-provider/swagger-ui/index.html) and [live Swagger UI here on Fineract.dev](https://sandbox.mifos.community/fineract-provider/swagger-ui/index.html).\n\nApache Fineract supports client code generation using [Swagger Codegen](https://github.com/swagger-api/swagger-codegen) based on the [OpenAPI Specification](https://swagger.io/specification/).  For more instructions on how to generate the client code, check [fineract-doc/src/docs/en/chapters/sdk/client.adoc](fineract-doc/src/docs/en/chapters/sdk/client.adoc).\n\n\n\u003cbr\u003eAPI CLIENTS (Web UIs, Mobile, etc.)\n============\n\n* https://github.com/openMF/community-app/ is the \"traditional\" Reference Client App Web UI for the API offered by this project\n* https://github.com/openMF/web-app is the next generation UI rewrite also using this project's API\n* https://github.com/openMF/android-client is an Android Mobile App client for this project's API\n* https://github.com/openMF has more related proejcts\n\n\n\u003cbr\u003eONLINE DEMOS\n============\n\n* [sandbox.mifos.community](https://sandbox.mifos.community) always runs the latest version of this code\n* [demo.mifos.io](https://demo.mifos.io) A demo account is provided for users to experience the functionality of the Community App.  Users can use \"mifos\" for USERNAME and \"password\" for PASSWORD (without quotation marks).\n* [Swagger-UI Demo video](https://www.youtube.com/watch?v=FlVd-0YAo6c) This is a demo video for Swagger-UI documentation, more information [here](https://github.com/apache/fineract#swagger-ui-documentation).\n\n\n\u003cbr\u003eDEVELOPERS\n============\nPlease see \u003chttps://cwiki.apache.org/confluence/display/FINERACT/Contributor%27s+Zone\u003e for the developers wiki page.\n\nPlease refer to \u003chttps://cwiki.apache.org/confluence/display/FINERACT/Fineract+101\u003e for the first-time contribution to this project.\n\nPlease see \u003chttps://cwiki.apache.org/confluence/display/FINERACT/How-to+articles\u003e for technical details to get started.\n\nPlease visit [our JIRA Dashboard](https://issues.apache.org/jira/secure/Dashboard.jspa?selectPageId=12335824) to find issues to work on, see what others are working on, or open new issues.\n\n\n\u003cbr\u003eVIDEO DEMONSTRATION\n============\n\nApache Fineract / Mifos X Demo (November 2016) - \u003chttps://www.youtube.com/watch?v=h61g9TptMBo\u003e\n\n\u003cbr\u003eSWAGGER UI DEMONSTRATION\n============\n\nWe use Swagger-UI to generate and maintain our API documentation, you can see the demo video [here](https://www.youtube.com/watch?v=FlVd-0YAo6c) or a live version\n[here](https://sandbox.mifos.community/fineract-provider/swagger-ui/index.html). If you interested to know more about Swagger-UI you can check their [website](https://swagger.io/).\n\n\u003cbr\u003eGOVERNANCE AND POLICIES\n=======================\n\n[Becoming a Committer](https://cwiki.apache.org/confluence/display/FINERACT/Becoming+a+Committer)\ndocuments the process through which you can become a committer in this project.\n\n\n\u003cbr\u003eERROR HANDLING GUIDELINES\n------------------\n* When catching exceptions, either rethrow them, or log them.  Either way, include the root cause by using `catch (SomeException e)` and then either `throw AnotherException(\"..details..\", e)` or `LOG.error(\"...context...\", e)`.\n* Completely empty catch blocks are VERY suspicous!  Are you sure that you want to just \"swallow\" an exception?  Really, 100% totally absolutely sure?? ;-) Such \"normal exceptions which just happen sometimes but are actually not really errors\" are almost always a bad idea, can be a performance issue, and typically are an indication of another problem - e.g. the use of a wrong API which throws an Exception for an expected condition, when really you would want to use another API that instead returns something empty or optional.\n* In tests, you'll typically never catch exceptions, but just propagate them, with `@Test void testXYZ() throws SomeException, AnotherException`..., so that the test fails if the exception happens.  Unless you actually really want to test for the occurence of a problem - in that case, use [JUnit's Assert.assertThrows()](https://github.com/junit-team/junit4/wiki/Exception-testing) (but not `@Test(expected = SomeException.class)`).\n* Never catch `NullPointerException` \u0026 Co.\n\n\u003cbr\u003eLOGGING GUIDELINES\n------------------\n* We use [SLF4J](http://www.slf4j.org) as our logging API.\n* Never, ever, use `System.out` and `System.err` or `printStackTrace()` anywhere, but always `LOG.info()` or `LOG.error()` instead.\n* Use placeholder (`LOG.error(\"Could not... details: {}\", something, exception)`) and never String concatenation (`LOG.error(\"Could not... details: \" + something, exception)`)\n* Which Log Level is appropriate?\n    * `LOG.error()` should be used to inform an \"operator\" running Fineract who supervises error logs of an unexpected condition.  This includes technical problems with an external \"environment\" (e.g. can't reach a database), and situations which are likely bugs which need to be fixed in the code.  They do NOT include e.g. validation errors for incoming API requests - that is signaled through the API response - and does (should) not be logged as an error.  (Note that there is no _FATAL_ level in SLF4J; a \"FATAL\" event should just be logged as an _ERROR_.)\n    * `LOG.warn()` should be using sparingly.  Make up your mind if it's an error (above) - or not!\n    * `LOG.info()` can be used notably for one-time actions taken during start-up.  It should typically NOT be used to print out \"regular\" application usage information.  The default logging configuration always outputs the application INFO logs, and in production under load, there's really no point to constantly spew out lots of information from frequently traversed paths in the code about what's going on.  (Metrics are a better way.)  `LOG.info()` *can* be used freely in tests though.\n    * `LOG.debug()` can be used anywhere in the code to log things that may be useful during investigations of specific problems.  They are not shown in the default logging configuration, but can be enabled for troubleshooting.  Developers should typically \"turn down\" most `LOG.info()` which they used while writing a new feature to \"follow along what happens during local testing\" to `LOG.debug()` for production before we merge their PRs.\n    * `LOG.trace()` is not used in Fineract.\n\nPull Requests\n-------------\n\nWe request that your commit message include a FINERACT JIRA issue, and a one-liner that describe the changes.\nStart with an upper case imperative verb (not past form), and a short but concise clear description. (E.g. \"FINERACT-821: Add enforced HideUtilityClassConstructor checkstyle\").\n\nIf your PR is failing to pass our CI build due to a test failure, then:\n\n1. Understand if the failure is due to your PR or an unrelated unstable test.\n1. If you suspect it is because of a \"flaky\" test, and not due to a change in your PR, then please do not simply wait for an active maintainer to come and help you, but instead be a proactive contributor to the project - see next steps.  Do understand that we may not review PRs that are not green - it is the contributor's (that's you!) responsability to get a proposed PR to pass the build, not primarily the maintainers.\n1. Search for the name of the failed test on https://issues.apache.org/jira/, e.g. for `AccountingScenarioIntegrationTest` you would find [FINERACT-899](https://issues.apache.org/jira/browse/FINERACT-899).\n1. If you happen to read in such bugs that tests were just recently fixed, or ignored, then rebase your PR to pick up that change.\n1. If you find previous comments \"proving\" that the same test has arbitrarily failed in at least 3 past PRs, then please do yourself raise a small separate new PR proposing to add an `@Disabled // TODO FINERACT-123` to the respective unstable test (e.g. [#774](https://github.com/apache/fineract/pull/774)) with the commit message mentioning said JIRA, as always.  (Please do NOT just `@Disabled` any existing tests mixed in as part of your larger PR.)\n1. If there is no existing JIRA for the test, then first please evaluate whether the failure couldn't be a (perhaps strange) impact of the change you are proposing after all.  If it's not, then please raise a new JIRA to document the suspected Flaky Test, and link it to [FINERACT-850](https://issues.apache.org/jira/browse/FINERACT-850).  This will allow the next person coming along hitting the same test failure to easily find it, and eventually propose to ignore the unstable test.\n1. Then (only) Close and Reopen your PR, which will cause a new build, to see if it passes.\n1. Of course, we very much appreciate you then jumping onto any such bugs and helping us figure out how to fix all ignored tests!\n\n[Pull Request Size Limit](https://cwiki.apache.org/confluence/display/FINERACT/Pull+Request+Size+Limit)\ndocuments that we cannot accept huge \"code dump\" Pull Requests, with some related suggestions.\n\nGuideline for new Feature commits involving Refactoring: If you are submitting PR for a new Feature,\nand it involves refactoring, try to differentiate \"new Feature code\" with \"Refactored\" by placing\nthem in different commits. This helps review to review your code faster.\n\nWe have an automated Bot which marks pull requests as \"stale\" after a while, and ultimately automatically closes them.\n\n\nMerge Strategy\n--------------\n\nThis project's committers typically prefer to bring your Pull Requests in through _Rebase and Merge_ instead of _Create a Merge Commit_. (If you are unfamiliar with GitHub's UI re. this, note the somewhat hidden little triangle drop-down at the bottom of PR, visible only to committers, not contributors.)  This avoids the \"merge commits\" which we consider to be somewhat \"polluting\" the projects commits log history view.  We understand this doesn't give an easy automatic reference to the original PR (which GitHub automatically adds to the Merge Commit message it generates), but we consider this an only very minor inconvenience; it's typically relatively easy to find the original PR even just from the commit message, and JIRA.\n\nWe expect most proposed PRs to typically consist of a single commit.  Committers may use _Squash and merge_ to combine your commits at merge time, and if they do so will rewrite your commit message as they see fit.\n\nNeither of these two are hard absolute rules, but mere conventions.  Multiple commits in single PR make sense in certain cases (e.g. branch backports).\n\n\nDependency Upgrades\n-------------------\n\nThis project uses a number of 3rd-party libraries, and this section provides some guidance for their updates. We have set-up [Renovate's bot](https://renovate.whitesourcesoftware.com) to automatically raise Pull Requests for our review when new dependencies are available [FINERACT-962](https://issues.apache.org/jira/browse/FINERACT-962).\n\nUpgrades sometimes require package name changes.  Changed code should ideally have test coverage.\n\nOur `ClasspathHellDuplicatesCheckRuleTest` detects classes that appear in more than 1 JAR.  If a version bump in [`build.gradle`](https://github.com/search?q=repo%3Aapache%2Ffineract+filename%3Abuild.gradle\u0026type=Code\u0026ref=advsearch\u0026l=\u0026l=) causes changes in transitives dependencies, then you may have to add related `exclude` to our [`dependencies.gradle`](https://github.com/apache/fineract/search?q=dependencies.gradle).  Running `./gradlew dependencies` helps to understand what is required.\n\n\nMore Information\n============\nMore details of the project can be found at \u003chttps://cwiki.apache.org/confluence/display/FINERACT\u003e.\n","funding_links":[],"categories":["Java","Other"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapache%2Ffineract","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapache%2Ffineract","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapache%2Ffineract/lists"}