| commit | 420d26a67964e660ee1456875ad904fbea53ee5b | [log] [tgz] |
|---|---|---|
| author | Michael Vorburger <mike@vorburger.ch> | Thu Oct 22 01:12:20 2020 +0200 |
| committer | Aleksandar Vidakovic <vidakovic@users.noreply.github.com> | Sat Oct 24 23:36:03 2020 +0200 |
| tree | 3c573aa3d65c84c59976d9d0493187c14f229aae | |
| parent | 43ef6e19839992fbc4b7d29a933c2b41bf8d64b7 [diff] |
Minor: CallSubject.hasHttpStatus() throws unchecked CallFailedRuntimeException
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. Visit our JIRA Dashboard to find issues to work on, see what others are working on, or open new issues.
to start contributing to this project in the online web-based IDE GitPod.io right away! (You may initially have to press F1 to Find Command and run “Java: Start Language Server”.) It's of course also possible to contribute with a “traditional” local development environment (see below).
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 “Hello!” introduction email; we’re a friendly bunch, and look forward to hearing from you.
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.7 -p 3306:3306 -e MYSQL_ROOT_PASSWORD=mysql -d mysql:5.7
and stop and destroy it like this:
docker rm -f mysql-5.7
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.
Tomcat v9 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 9 is required.)
Run the following commands:
./gradlew createDB -PdbName=fineract_tenants./gradlew createDB -PdbName=fineract_default./gradlew bootRun./gradlew clean bootJar to build a modern cloud native fully self contained JAR file which will be created at build/libs directory.java -jar build/libs/fineract-provider.jar (does not require external Tomcat)The tenants database connection details are configured via environment variables (as with Docker container), e.g. like this:
export fineract_tenants_pwd=verysecret ... java -jar fineract-provider.jar
./gradlew clean war to build a traditional WAR file which will be created at build/libs directory.We recommend using the JAR instead of the WAR file deployment, because it's much easier.
Note 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.
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 integrationTestIt is possible to run Fineract in Eclipse IDE and also to debug Fineract using Eclipse's debugging facilities. To do this, you need to create the Eclipse project files and import the project into an Eclipse workspace:
You can also use Eclipse Junit support to run tests in Eclipse (Run As->Junit Test)
Finally, modifying source code in Eclipse automatically triggers hot code replace to a running instance, allowing you to immediately test your changes
It is possible to do a ‘one-touch’ installation of Fineract using containers (AKA “Docker”). Fineract now packs the mifos community-app web UI in it's docker deploy. You can now run and test fineract with a GUI directly from the combined docker builds. This includes the database running in a 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.
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{"status":"UP"}mifos and password passwordThe docker-compose.yml will build the fineract container from the source based on the Dockerfile. You could change that to use the pre-built container image instead of having to re-build it.
https://hub.docker.com/r/apache/fineract 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. (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-startupTo 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.
The file 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 gradle/wrapper https://github.com/apache/fineract/raw/develop/gradle/wrapper/gradle-wrapper.jar
(or)
curl --insecure -L https://github.com/apache/fineract/raw/develop/gradle/wrapper/gradle-wrapper.jar > gradle/wrapper/gradle-wrapper.jar
./gradlew rat. A report will be generated under build/reports/rat/rat-report.txtMessaging configuration is disabled by default. If you want to enable it and register some message listeners, application needs to be started with the proper Spring profile, ie -Dspring.profiles.active=activeMqEnabled (or one of the other Spring ways to configure it).
This project enforces its code conventions using checkstyle.xml through Checkstyle and 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:
`./gradlew spotlessApply`
Since 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).
You can also check for Spotless violations (only; but normally don't have to, because the regular build full already includes this anyway):
`./gradlew spotlessCheck`
We recommend that you configure your favourite Java IDE to match those conventions. For Eclipse, you can go to Window > Java > Code Style and import our config/fineractdev-formatter.xml under formatter section and 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. 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 Fineract is documented in apiLive.htm, and the apiLive.htm can be viewed on Fineract.dev. If you have your own Fineract instance running, you can find this documentation under /fineract-provider/api-docs/apiLive.htm.
The Swagger documentation (work in progress; see FINERACT-733) can be accessed under /fineract-provider/swagger-ui/index.html and live Swagger UI here on Fineract.dev.
Apache Fineract supports client code generation using Swagger Codegen based on the OpenAPI Specification. For more instructions on how to generate the client code, check docs/developers/swagger/client.md.
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 our JIRA Dashboard to find issues to work on, see what others are working on, or open new issues.
Apache Fineract / Mifos X Demo (November 2016) - https://www.youtube.com/watch?v=h61g9TptMBo
We use Swagger-UI to generate and maintain our API documentation, you can see the demo video here or a live version here. If you interested to know more about Swagger-UI you can check their website.
Becoming a Committer documents the process through which you can become a committer in this project.
catch (SomeException e) and then either throw AnotherException("..details..", e) or LOG.error("...context...", e).@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() (but not @Test(expected = SomeException.class)).NullPointerException & Co.System.out and System.err or printStackTrace() anywhere, but always LOG.info() or LOG.error() instead.LOG.error("Could not... details: {}", something, exception)) and never String concatenation (LOG.error("Could not... details: " + something, exception))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.)LOG.warn() should be using sparingly. Make up your mind if it's an error (above) - or not!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.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.LOG.trace() is not used in Fineract.We request that your commit message include a FINERACT JIRA issue, recommended to be put in parenthesis add the end of the first line. Start with an upper case imperative verb (not past form), and a short but concise clear description. (E.g. Add enforced HideUtilityClassConstructor checkstyle (FINERACT-821) or Fix inability to reschedule when interest accrued larger than EMI (FINERACT-1109) etc.).
If your PR is failing to pass our CI build due to a test failure, then:
AccountingScenarioIntegrationTest you would find FINERACT-899.@Disabled // TODO FINERACT-123 to the respective unstable test (e.g. #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.)Pull Request Size Limit documents that we cannot accept huge “code dump” Pull Requests, with some related suggestions.
Guideline for new Feature commits involving Refactoring: If you are submitting PR for a new Feature, and it involves refactoring, try to differentiate “new Feature code” with “Refactored” by placing them in different commits. This helps review to review your code faster.
We have an automated Bot which marks pull requests as “stale” after a while, and ultimately automatically closes them.
This 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.
We 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.
Neither of these two are hard absolute rules, but mere conventions. Multiple commits in single PR make sense in certain cases (e.g. branch backports).
This project uses a number of 3rd-party libraries, and this section provides some guidance for their updates. We have set-up Renovate's bot to automatically raise Pull Requests for our review when new dependencies are available FINERACT-962.
Upgrades sometimes require package name changes. Changed code should ideally have test coverage.
Our ClasspathHellDuplicatesCheckRuleTest detects classes that appear in more than 1 JAR. If a version bump in build.gradle causes changes in transitives dependencies, then you may have to add related exclude to our dependencies.gradle. Running ./gradlew dependencies helps to understand what is required.
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 tar.gz available on http://fineract.apache.org.
Before you use Gradle to create a release you need to make sure that you provide the proper GPG parameters. You have to options:
signing.gnupg.keyName=7890ABCD signing.gnupg.passphrase=secret
IMPORTANT: Do not set your GPG secrets in one of the project gradle.properties and double check that you are not accidentally committing them to Git.
The release command would look then look like this:
./gradlew -Pfineract.release clean build
./gradlew -Pfineract.release -Psigning.gnupg.keyName=7890ABCD -Psigning.gnupg.passphrase=secret clean build
NOTE: Let's assume your GPG key ID would be “ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890ABCD” then you have to use the last 8 characters (i. e. “7890ABCD”) for the signing plugin property “signing.gnupg.keyName”.
Above tasks will create the following files in folder build/distributions:
The signatures are automatically verified by the build script. It will throw an exception if the verification fails.
Additionally, you can verify the validity of the release distribution files e. g. with:
gpg --verify build/distributions/apache-fineract-1.4.0-binary.tar.gz.asc
The output should look somewhat like this:
gpg: assuming signed data in 'build/distributions/apache-fineract-1.4.0-binary.tgz' gpg: Signature made Mi 26 Aug 2020 17:17:45 CEST gpg: using RSA key ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890ABCD gpg: Good signature from "Aleksandar Vidakovic (Apache Fineract Release Manager) <aleks@apache.org>" [ultimate]
NOTE: All commands shown above are assuming that the current working directory is the project root folder.
More details of the project can be found at https://cwiki.apache.org/confluence/display/FINERACT.