Re: Update README

[Adam Monsen]

On Fri, Oct 3, 2025 at 6:39 AM Felix van Hove <fvanh...@gmx.de.invalid>
wrote:

> https://github.com/apache/fineract/pull/5076
>

TL;DR - Great work so far!

2. I suggest to move some parts of the current README somewhere else.
>

Yes! 100% agree. I'd love to get the readme down to "one page" (whatever
that means--let's just say *very* succinct). The rest can live in official
docs or wiki. ~50% of the existing readme content should be moved to the
official docs and ~50% to the wiki.

( By "official docs" I mean the asciidoc sources in fineract-doc
<https://github.com/apache/fineract/tree/develop/fineract-doc/src/docs/en>.
)

I attached my suggestion. You can view it rendered here
<https://codeberg.org/meonkeys/fineract-brief-readme> or here
<https://git.disroot.org/meonkeys/fineract-brief-readme> (wait for it --
sometimes it takes a few seconds for the charts to render). Of course if
you accept this it's still only a third of the work, the rest of the work
is updating official docs, wiki, and a couple other markdown files (see
below).


> - First of all, have you had a look at the CONTRIBUTING document? Contrary
> to the README, it's too short. Is it okay, if I move what is now
> "Guidelines for Contributing Code" over?
>

Sure, or to the official docs. And CONTRIBUTING.md should be updated and
kept short.


> - Secondly, could we not move half of what is under "Instructions" now to
> the documentation page (https://fineract.apache.org/docs/current/)


Yes, please do.


> 3. I would like to add a section "Troubleshooting", but need your input
> for it.
>

This can go in the official docs too, once we have content for it.


> 4. The current text remains extraordinarily long for a README, even if we
> move some sections somewhere else. To mitigate its complexity I have added
> a hopefully better structure to it (moved sections etc.) and a Table of
> contents. Okay?


I don't want to add nor maintain a TOC. Let's just make the readme so short
we don't need one. (side note: many tools generate a TOC for you by
scanning Markdown headings, e.g. Vim Markdown
<https://github.com/preservim/vim-markdown> and Markdown Viewer
<https://addons.mozilla.org/en-US/firefox/addon/markdown-viewer-webext/>).

5. I've removed and/or merged a few sections.
>

👍

6. I'm not happy with the current DATABASE section and its position,
> suggestions welcome.


Move to wiki or official docs or axe it.

Final thought: content in STATIC_WEAVING.md should be moved to official
docs or wiki.

# Apache Fineract: A Platform for Microfinance

[![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)
[![Docker 
Hub](https://img.shields.io/docker/pulls/apache/fineract.svg?logo=Docker)](https://hub.docker.com/r/apache/fineract)
[![Docker 
Build](https://github.com/apache/fineract/actions/workflows/publish-dockerhub.yml/badge.svg)](https://github.com/apache/fineract/actions/workflows/publish-dockerhub.yml)
[![Technical 
Debt](https://sonarcloud.io/api/project_badges/measure?project=apache_fineract&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=apache_fineract)

<!--
This mission statement is under active development.
See https://lists.apache.org/thread/p43xpk5382yjvc11hcxbydbt0m1ym5p4
TODO: update this section once it is finalized.
-->

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 3 billion underbanked and unbanked.

## Quick reference

[Wiki](https://cwiki.apache.org/confluence/display/FINERACT/) | [Issue 
tracker](https://issues.apache.org/jira/secure/Dashboard.jspa?selectPageId=12335824)
 | [Live chat](https://mifos.slack.com/archives/C028634A61L) | [Mailing 
list](https://lists.apache.org/list?dev@fineract.apache.org) | [Official 
docs](https://fineract.apache.org/docs/current/) | 
[Contributing](https://github.com/apache/fineract/blob/develop/CONTRIBUTING.md) 
| [Code of 
Conduct](https://github.com/apache/fineract/blob/develop/CODE_OF_CONDUCT.md) | 
[Fineract 
101](https://cwiki.apache.org/confluence/display/FINERACT/Fineract+101) | 
[How-to 
articles](https://cwiki.apache.org/confluence/display/FINERACT/How-to+articles)

### start server

Run the following commands:

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

Fineract is now running, and will be listening for API requests on port 8443 by 
default.

[Read more about dev env 
setup](https://fineract.apache.org/docs/current/#_fineract_development_environment).

### run some tests

Here's how to run the set of relatviely fast and indepedent Fineract tests:

```bash
./gradlew test -x :twofactor-tests:test -x :oauth2-tests:test -x 
:integration-tests:test
```

This runs nearly 1,000 tests and completes in a few minutes on decent hardware, 
and shouldn't need any special servers/services running.

[Read our full testing 
instructions](https://fineract.apache.org/docs/current/#_testing).

### deploy to prod

Running Fineract just to try it out is relatively easy. This might take a few 
minutes to complete for a developer who has done it before. If you intend to 
use it for customers, be aware that a proper Fineract production deployment can 
be very complex, costly, and time-consuming. Considerations include, for 
starters: Security, privacy, compliance, performance, service availability, and 
backups. The Fineract project does not provide a comprehensive guide for 
deploying Fineract in production. You will need dedicated IT resources skilled 
in enterprise Java applications. Or you can pay a vendor for Fineract 
deployment and maintenance.

You will find tips and tricks for deploying and securing Fineract in our 
[official documentation](https://fineract.apache.org/docs/current/), and there 
are also [community-maintained use cases on the 
wiki](https://cwiki.apache.org/confluence/display/FINERACT/Hosting+Fineract).

## Security

If you believe you have found a security vulnerability, [let us know 
privately](https://fineract.apache.org/#contribute).

[Read more about security during development and 
deployment](https://fineract.apache.org/docs/current/#_security).

## License

Fineract is licensed under the terms of the [Apache License, Version 
2.0](https://www.apache.org/licenses/LICENSE-2.0.html).

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 Liquibase 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 Liquibase library 
and/or use another JDBC driver. As discussed in 
[LEGAL-462](https://issues.apache.org/jira/browse/LEGAL-462), this project 
therefore complies with the [Apache Software Foundation third-party license 
policy](https://www.apache.org/legal/resolved.html).

## additional resources

* ["traditional" Reference Client App Web UI for the API offered by this 
project](https://github.com/openMF/community-app/)
* [next generation UI rewrite also using this project's 
API](https://github.com/openMF/web-app)
* [Android Mobile App client for this project's 
API](https://github.com/openMF/android-client)
* [more related projects](https://github.com/openMF)
* [sandbox: demo server with latest version of this 
code](https://sandbox.mifos.community)
* [demo.mifos.io: community app](https://demo.mifos.io) -- username: `mifos`, 
password: `password`
* [Swagger-UI Demo video](https://www.youtube.com/watch?v=FlVd-0YAo6c)
* [Apache Fineract / Mifos X Demo video from November 
2016](https://www.youtube.com/watch?v=h61g9TptMBo)
* [Fineract Swagger-UI demo video from August 
2020](https://www.youtube.com/watch?v=FlVd-0YAo6c)

## repository analytics

### star history

<a 
href="https://next.ossinsight.io/widgets/official/analyze-repo-stars-history?repo_id=48418599";
 target="_blank" style="display: block" align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" 
srcset="https://next.ossinsight.io/widgets/official/analyze-repo-stars-history/thumbnail.png?repo_id=48418599&image_size=auto&color_scheme=dark";
 width="721" height="auto">
    <img alt="Star History of apache/fineract" 
src="https://next.ossinsight.io/widgets/official/analyze-repo-stars-history/thumbnail.png?repo_id=48418599&image_size=auto&color_scheme=light";
 width="721" height="auto">
  </picture>
</a>

### where our stars come from

<a 
href="https://next.ossinsight.io/widgets/official/analyze-repo-stars-map?repo_id=48418599&activity=stars";
 target="_blank" style="display: block" align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" 
srcset="https://next.ossinsight.io/widgets/official/analyze-repo-stars-map/thumbnail.png?repo_id=48418599&activity=stars&image_size=auto&color_scheme=dark";
 width="721" height="auto">
    <img alt="Star Geographical Distribution of apache/fineract" 
src="https://next.ossinsight.io/widgets/official/analyze-repo-stars-map/thumbnail.png?repo_id=48418599&activity=stars&image_size=auto&color_scheme=light";
 width="721" height="auto">
  </picture>
</a>

### activity

*We use the [ASF's Jira](https://issues.apache.org/jira/projects/FINERACT/) to 
track issues.*

<a 
href="https://next.ossinsight.io/widgets/official/compose-last-28-days-stats?repo_id=48418599";
 target="_blank" style="display: block" align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" 
srcset="https://next.ossinsight.io/widgets/official/compose-last-28-days-stats/thumbnail.png?repo_id=48418599&image_size=auto&color_scheme=dark";
 width="655" height="auto">
    <img alt="Performance Stats of apache/fineract - Last 28 days" 
src="https://next.ossinsight.io/widgets/official/compose-last-28-days-stats/thumbnail.png?repo_id=48418599&image_size=auto&color_scheme=light";
 width="655" height="auto">
  </picture>
</a>

### active contributors

<a 
href="https://next.ossinsight.io/widgets/official/compose-recent-active-contributors?repo_id=48418599&limit=30";
 target="_blank" style="display: block" align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" 
srcset="https://next.ossinsight.io/widgets/official/compose-recent-active-contributors/thumbnail.png?repo_id=48418599&limit=30&image_size=auto&color_scheme=dark";
 width="655" height="auto">
    <img alt="Active Contributors of apache/fineract - Last 28 days" 
src="https://next.ossinsight.io/widgets/official/compose-recent-active-contributors/thumbnail.png?repo_id=48418599&limit=30&image_size=auto&color_scheme=light";
 width="655" height="auto">
  </picture>
</a>