How to install Apache Fineract: Docker, Docker Compose and Kubernetes (2026)

How to install Apache Fineract: Docker, Docker Compose and Kubernetes (2026)

The quickest way to install Apache Fineract is to run its container next to a PostgreSQL database, pass it a handful of FINERACT_* environment variables, and log in as mifos / password on the default tenant, then change that password straight away. Before you pull anything, know two things: the apache/fineract:latest image on Docker Hub is a build of the development branch, not a release, and the project ships Kubernetes manifests for a demo but no Helm chart.

This guide covers all three routes, docker run, Docker Compose and Kubernetes, for the 1.16.1 release (published October 26, 2026). Every file path, variable and default below was checked against the 1.16.1 tag of the Apache Fineract repository. We run managed Fineract for a living, so we have also marked the parts of the shipped setup you should not carry into production.

What you need before you start

  • Docker with Compose v2 (the docker compose command). The project README also supports Podman with Podman Compose.
  • At least 4 GB of memory for Docker, as our local development guide recommends. The project's docker-compose.yml caps the Fineract JVM at 1 GB of heap (-Xmx1G in config/docker/env/fineract-common.env), docker-compose-development.yml raises it to 2 GB through config/docker/env/debug.env, and the database needs room on top of that.
  • Free ports: 8443 for the API, 5432 for PostgreSQL (the compose files always publish it), 4200 for the web app, and 5000 if you use docker-compose.yml, which publishes the Java debug port. The development file also takes 3000, 3100, 9090 and the Tempo ports.
  • To build a release image yourself (you will want to, see below): Git and a JDK 25. At 1.16.1, build.gradle sets a Java 25 toolchain, and gradle.properties gives the Gradle JVM up to 12 GB of heap (-Xmx12g), so build on a machine with real memory, not a small CI runner.

You do not need Java installed to run the container. The image is built with Jib on top of azul/zulu-openjdk-alpine:25-jre-headless (see the jib block in fineract-provider/build.gradle), so the runtime comes with it.

Pick the database: PostgreSQL

Fineract needs two databases, not one. fineract_tenants is the tenant store, a registry of tenants and how to reach them. fineract_default holds the data for the default tenant: clients, loans, the general ledger. Fineract migrates both on startup, but it does not create the empty databases. The project's own init scripts do that (config/docker/postgresql/docker-entrypoint-initdb.d/01-init.sh for PostgreSQL, config/docker/mysql/docker-entrypoint-initdb.d/01-databases.sql for MySQL and MariaDB).

A local Apache Fineract install. Your browser loads the Mifos web app on localhost:4200 and sends REST calls straight to Apache Fineract at https://localhost:8443/fineract-provider. Fineract connects to one PostgreSQL 18 server holding two databases: fineract_tenants, the tenant store that lists tenants and how to reach them, and fineract_default, the data of the default tenant such as clients, loans and the ledger.
What a local install runs: the web app, the Fineract API, and one PostgreSQL server holding two databases.

For a new install, use PostgreSQL. It is the default in application.properties (driver org.postgresql.Driver, URL jdbc:postgresql://localhost:5432/fineract_tenants), and the shipped compose files use postgres:18.3. MariaDB and MySQL still have CI workflows at 1.16.1 (build-mariadb.yml, build-mysql.yml), but the README marks both as deprecated, and the accepted FSIP-9 proposal is to support PostgreSQL only.

There is also a practical catch. The README says the official image includes the PostgreSQL JDBC driver only; the MariaDB and MySQL drivers are left out for licensing reasons. On those engines you supply the driver JAR yourself. The image puts /app/plugins/* on its classpath (extraClasspath in the jib block), so a mounted driver goes there, and you set FINERACT_HIKARI_DRIVER_SOURCE_CLASS_NAME, a matching JDBC URL and FINERACT_DEFAULT_TENANTDB_PORT=3306, as the README's MariaDB example does. If you are already on MySQL and want out, we wrote up the MySQL-to-PostgreSQL migration separately.

Which image to run (read this before you pull)

The project publishes apache/fineract on Docker Hub, but the tags are not what most people assume. When we checked on November 18, 2026, latest and develop pointed at the same image digest, rebuilt from commits to the development branch. The newest release-numbered tag was 1.12.1. There were no 1.13.0 to 1.16.1 tags, even though the publish workflow (.github/workflows/publish-dockerhub.yml) is written to push them.

So apache/fineract:latest is fine for a quick look, as long as you accept that it is whatever landed on develop recently. To run 1.16.1, build the image from the release tag. The README's container instructions build the image the same way, with Jib, but from a fresh clone of the develop branch. Check out the release tag first:

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

That loads an image named fineract into your local Docker, tagged latest plus the project version. It is also the image name the shipped compose files expect, so the next two sections both use it.

Option 1: docker run

Start PostgreSQL on its own network with a named volume, so the data survives a container restart. On the 18.x images the volume path is /var/lib/postgresql, not the older /var/lib/postgresql/data.

docker network create fineract

docker run -d --name fineract-db --network fineract \
  -e POSTGRES_USER=root \
  -e POSTGRES_PASSWORD=change-me \
  -v fineract-pgdata:/var/lib/postgresql \
  postgres:18.3

Once docker exec fineract-db pg_isready -U root -d postgres reports that it is accepting connections, create the two databases:

docker exec fineract-db psql -U root -d postgres \
  -c 'CREATE DATABASE fineract_tenants;' \
  -c 'CREATE DATABASE fineract_default;'

Then start Fineract. The defaults already assume PostgreSQL on port 5432, a tenant database called fineract_default and a tenant identifier of default, so you only override what differs:

docker run -d --name fineract --network fineract -p 8443:8443 \
  -e FINERACT_HIKARI_JDBC_URL=jdbc:postgresql://fineract-db:5432/fineract_tenants \
  -e FINERACT_HIKARI_USERNAME=root \
  -e FINERACT_HIKARI_PASSWORD=change-me \
  -e FINERACT_DEFAULT_TENANTDB_HOSTNAME=fineract-db \
  -e FINERACT_DEFAULT_TENANTDB_UID=root \
  -e FINERACT_DEFAULT_TENANTDB_PWD=change-me \
  -e FINERACT_DEFAULT_TENANTDB_TIMEZONE=Europe/Berlin \
  fineract:latest

docker logs -f fineract

Swap fineract:latest for apache/fineract:latest if you skipped the build and only want a quick look. Set the timezone to your institution's own; the next sections explain why it matters.

Option 2: the Docker Compose files the project ships

The repository root at 1.16.1 has a whole family of compose files. The ones that matter for an install:

  • docker-compose.yml: PostgreSQL plus Fineract. Publishes 8443 for the API and 5000 for a Java debugger.
  • docker-compose-postgresql.yml: the same pair without the debug port.
  • docker-compose-development.yml: the setup the README documents, which adds Loki, Prometheus, Grafana and Tempo.
  • docker-compose-mariadb.yml and docker-compose-mysql.yml: at 1.16.1 these start only a database (mariadb:12.2 or mysql:8), with no Fineract service.
  • docker-compose-web-app.yml and docker-compose-community-app.yml: front ends, covered below.
  • docker-compose-postgresql-activemq.yml, docker-compose-postgresql-kafka.yml and docker-compose-postgresql-kafka-msk.yml: message-broker setups for external events and remote batch workers.

Every file above that runs Fineract uses the locally built fineract:latest image (config/docker/compose/fineract.yml), so build it first as shown above. Then, from the repository root:

docker compose up -d
docker compose logs -f fineract

The repository root matters. The compose files mount paths through ${PWD}, including build/fineract/logs for Fineract's log output, and the container runs as user 1000:1000 (the user line in config/docker/compose/fineract.yml). If you hit file permission errors, the README tells you to set FINERACT_USER and FINERACT_GROUP to your own id -u and id -g. It points at fineract-common.env, but Compose fills in that user line from your shell or a .env file, so export them there.

For the full observability stack, install the Loki log driver first, as the README describes, then start the development file:

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

Read config/docker/env/fineract-common.env before you build anything on top of this. It is a developer setup, and the README says so in a caution box: "Our images are NOT production-ready." The shared env file sets SPRING_PROFILES_ACTIVE=test,diagnostics (the README is explicit that test must not be enabled in production), switches on a JDWP debug agent on port 5000, commits the database passwords to Git, and leaves the tenant timezone on Asia/Kolkata. And config/docker/compose/postgresql.yml mounts no named volume for the database, so treat that data as disposable.

The environment variables that matter

Fineract reads its configuration from FINERACT_* environment variables that map onto fineract-provider/src/main/resources/application.properties. These are the ones you will touch on a first install, with their 1.16.1 defaults:

VariableDefault at 1.16.1What it does
FINERACT_HIKARI_DRIVER_SOURCE_CLASS_NAMEorg.postgresql.DriverJDBC driver for the tenant store connection.
FINERACT_HIKARI_JDBC_URLjdbc:postgresql://localhost:5432/fineract_tenantsWhere the tenant store lives.
FINERACT_HIKARI_USERNAME / FINERACT_HIKARI_PASSWORDroot / postgresTenant store credentials.
FINERACT_HIKARI_MINIMUM_IDLE / FINERACT_HIKARI_MAXIMUM_POOL_SIZE3 / 10Hikari pool for the tenant store. Per-tenant pools take their sizes from the tenant store unless you override them with FINERACT_CONFIG_MIN_POOL_SIZE and FINERACT_CONFIG_MAX_POOL_SIZE.
FINERACT_DEFAULT_TENANTDB_HOSTNAME / _PORTlocalhost / 5432Server holding the default tenant's database.
FINERACT_DEFAULT_TENANTDB_UID / _PWDroot / postgresCredentials for that database.
FINERACT_DEFAULT_TENANTDB_NAMEfineract_defaultName of the default tenant's database.
FINERACT_DEFAULT_TENANTDB_IDENTIFIERdefaultThe value clients send in the Fineract-Platform-TenantId header.
FINERACT_DEFAULT_TENANTDB_TIMEZONEAsia/KolkataThe tenant's business timezone. Set it to yours.
FINERACT_DEFAULT_TENANTDB_MASTER_PASSWORD and FINERACT_DEFAULT_MASTER_PASSWORDfineractThe first encrypts the tenant database credentials stored in fineract_tenants. The second is only a fallback for when the first is unset, which the shipped application.properties never leaves it.
FINERACT_SERVER_SSL_ENABLED / FINERACT_SERVER_PORTtrue / 8443Built-in TLS with a self-signed certificate.
FINERACT_NODE_ID1Node identity, which matters once you run more than one instance.
FINERACT_LIQUIBASE_ENABLEDtrueRun database migrations on startup.

Two of these deserve a second look. The timezone default of Asia/Kolkata is the one that bites weeks later, when the business date and the nightly jobs run against the wrong day. The master password (FINERACT_DEFAULT_TENANTDB_MASTER_PASSWORD) encrypts the stored tenant credentials, so change it before the first start and use the same value on every instance. Our environment variables reference covers the rest, including operation modes, batch jobs and events.

First start: migrations, the default tenant and logging in

On the first start Fineract runs Liquibase against both databases. It migrates the tenant store, writes the default tenant row (identifier, timezone and connection details) from your FINERACT_DEFAULT_TENANTDB_* values, and then builds the tenant schema. The insert lives in db/changelog/tenant-store/parts/0002_initial_data.xml, which is why those values belong in place before the first boot, not after. The README says to wait for APACHE FINERACT IS READY in the log before you send requests.

The first start of Apache Fineract in order: the container starts with FINERACT_DEFAULT_TENANTDB_* already set, Liquibase migrates fineract_tenants, the default tenant row is written with identifier, timezone and connection details, Liquibase builds the tenant schema in fineract_default, APACHE FINERACT IS READY appears in the log and /actuator/health returns UP, then you log in as mifos / password and change that password first.
First boot, in order. Set the tenant variables before it starts, and change the default password before anything else.

Then check it. The API is not served from the root; everything sits under /fineract-provider, and the certificate is self-signed, hence -k:

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

A fresh instance answers {"status":"UP","groups":["liveness","readiness"]}. Now an authenticated call. Every request has to name its tenant, either with the header or with ?tenantIdentifier=default:

curl -k -u mifos:password \
  -H 'Fineract-Platform-TenantId: default' \
  https://localhost:8443/fineract-provider/api/v1/clients

An empty instance returns {"totalFilteredRecords":0,"pageItems":[]}. The Swagger UI is at https://localhost:8443/fineract-provider/swagger-ui/index.html.

The default login is mifos / password on tenant default. The user is seeded as id 1 by db/changelog/tenant/parts/0002_initial_data.xml, so it is the same on every Fineract install, it is printed in the README, and HTTP basic auth is on by default (FINERACT_SECURITY_BASICAUTH_ENABLED=true). Anyone who can reach your port can try it. Change it before you do anything else, in the web app or through the API:

curl -k -u mifos:password \
  -H 'Fineract-Platform-TenantId: default' \
  -H 'Content-Type: application/json' \
  -X POST https://localhost:8443/fineract-provider/api/v1/users/1/pwd \
  -d '{"password":"YOUR-NEW-PASSWORD","repeatPassword":"YOUR-NEW-PASSWORD"}'

These are application credentials, separate from the database ones. Changing the database password does nothing to the mifos login, and the reverse is true too. If the instance will not come up at all, our post on the first-boot errors everyone hits and the troubleshooting guide cover the usual suspects: the wrong path, the missing tenant header, a stuck Liquibase lock, a missing database.

Put the Mifos web app in front of it

Fineract ships no user interface. In the README's words, it "does not provide a UI, but provides an API." The usual front end is the Angular Mifos web app, which both the Fineract repo's compose file and its Kubernetes demo run. The older community-app is archived on GitHub, even though the Fineract repo still carries a docker-compose-community-app.yml for it. Skip that one.

The Fineract repo's docker-compose-web-app.yml runs openmf/web-app:master on port 4200. The web app's image fills in its configuration from environment variables when the container starts, so you can point it at your backend like this:

docker run -d --name mifos-web-app -p 4200:80 \
  -e FINERACT_API_URLS=https://localhost:8443 \
  -e FINERACT_API_URL=https://localhost:8443 \
  -e FINERACT_PLATFORM_TENANT_IDENTIFIER=default \
  openmf/web-app:master

Your browser calls the API directly, so open https://localhost:8443 once and accept the self-signed certificate (the README asks for the same), then go to http://localhost:4200 and log in as mifos. The web app's README recommends pinning a version tag for production; check which tags actually exist on Docker Hub before you pin one.

For anything beyond a laptop, serve the web app and the API from the same origin through a reverse proxy, so the browser never sees the backend's certificate. The Kubernetes demo in the Fineract repo shows the pattern: kubernetes/fineract-mifoscommunity-deployment.yml sets the web app's API URL to /fineract-provider and has nginx proxy that path to the Fineract service. Our UI options guide and the post on which Fineract front end to pick go further.

Kubernetes: what the repo ships, and what about Helm

The kubernetes/ directory at 1.16.1 holds four manifests and two scripts. kubectl-startup.sh creates a secret with a random database password, then applies, in order:

  • fineractmysql-configmap.yml and fineractmysql-deployment.yml: a single mariadb:12.2 pod on a hostPath persistent volume at /mnt/data, with an init script that creates fineract_tenants and fineract_default.
  • fineract-server-deployment.yml: one Fineract pod from apache/fineract:latest with a 2 Gi memory limit, liveness and readiness probes on /fineract-provider/actuator/health/liveness and /readiness, and a LoadBalancer service on 8443.
  • fineract-mifoscommunity-deployment.yml: the Mifos web app behind nginx, as a second LoadBalancer service on 9090.

The README runs it on minikube (cd fineract/kubernetes, minikube start, ./kubectl-startup.sh, then minikube service mifos-community) and logs you in with the same mifos / password. It is a demo. It pulls the moving latest image, keeps the database on a node's local disk, and publishes the API through a LoadBalancer service. Two details also do not line up as shipped: the manifest pairs apache/fineract:latest with MariaDB, while the README says that image carries only the PostgreSQL driver, and it sets FINERACT_HIKARI_DRIVER_CLASS_NAME, a name application.properties never reads (it reads FINERACT_HIKARI_DRIVER_SOURCE_CLASS_NAME). We have not run the manifests against 1.16.1, but we would not expect them to connect without changes.

Now Helm. There is no official Apache Fineract Helm chart. The repo contains none, and the "Helm Charts" section of the official 1.16.1 documentation reads, in full, "TBD" (source: fineract-doc/src/docs/en/chapters/development/kubernetes-helm.adoc). Artifact Hub lists several community charts named fineract, from different publishers and pinned to different Fineract versions, and none of them comes from the Apache Fineract project. If you use one, review it like any third-party code: which image it pulls, where the database lives, how it runs migrations, and how it handles secrets.

Whether you write your own manifests or adopt a chart, a real cluster deployment needs a few things the demo leaves out:

  • An image you built from a release tag and pushed to your own registry, pinned by version.
  • A managed or properly operated PostgreSQL outside the cluster's node disks.
  • Migrations as their own step. The official Kubernetes chapter says to run one instance with SPRING_PROFILES_ACTIVE=liquibase-only, which migrates and exits, and to set FINERACT_LIQUIBASE_ENABLED=false on the regular instances. A Kubernetes Job before each rollout fits this well.
  • Exactly one batch manager once you scale past one pod. Our instance types guide covers the read, write and batch modes.
  • TLS at the ingress and a private service for the API.

Our production guide walks through how that topology grows.

A short production checklist

TLS. The certificate inside the image is a self-signed development certificate (the keystore defaults to classpath:keystore.jks with password openmf). The official HTTPS chapter recommends a TLS-terminating proxy with rotating certificates; Fineract honours the X-Forwarded-For and X-Forwarded-Proto headers. If the proxy terminates TLS, the same chapter says you can set FINERACT_SERVER_SSL_ENABLED=false and FINERACT_SERVER_PORT=8080.

Remove the demo settings. Drop the test profile, the debug port and the committed passwords from anything you copied out of the repo. Change mifos / password and both master passwords, and narrow CORS, which defaults to any origin (FINERACT_SECURITY_CORS_ALLOWED_ORIGIN_PATTERNS=*). The security-hardening checklist has the rest.

Backups. Back up fineract_tenants and every tenant database on a schedule, and test a restore. Remember that the shipped compose stack keeps PostgreSQL data in no named volume at all.

COB and batch jobs. Close of Business and the other scheduled jobs run inside Fineract against each tenant's business date, which is one more reason the timezone has to be right. When you run several instances, only one may be the batch manager. See the COB guide, and the post on slow COB for when it starts taking hours.

Upgrades. Build and pin the new release, back up both databases, and let Liquibase run once before the application instances start. The schema moves forward, so your rollback plan is the backup you took. Read the release notes and our Liquibase migration guide first.

Monitoring. Use the liveness and readiness endpoints for probes. By default Fineract also exposes /fineract-provider/actuator/prometheus (FINERACT_MANAGEMENT_ENDPOINT_WEB_EXPOSURE_INCLUDE defaults to health,info,prometheus), and docker-compose-development.yml shows a working Prometheus, Grafana, Loki and Tempo setup. Our monitoring guide lists the metrics worth alerting on.

Or let someone else run it

Everything above is doable. It is also ongoing work: building images from tags because the registry stops at 1.12.1, owning the database and its backups, running migrations as a separate step, keeping one batch manager, and patching. If you would rather skip that, Finecko runs managed Apache Fineract with the Mifos web app included on every plan, hosted on Oracle Cloud (OCI) in Frankfurt by default, with other regions possible.

The Free plan covers up to 100 clients and is meant for evaluation, not production. Starter is EUR 449/month and Professional is EUR 1,599/month, and enterprise SLAs are set by contract. If you want to see a working instance before you decide whether to build your own, start on the Free plan. For the do-it-yourself side, see what it costs to run Fineract yourself.

FAQ

Is there an official Apache Fineract Docker image?

Yes, apache/fineract on Docker Hub, built by the project's own workflow. But latest tracks the development branch, and when we checked, the newest release tag there was 1.12.1. To run 1.16.1, check out the 1.16.1 tag and build the image with ./gradlew :fineract-provider:jibDockerBuild -x test.

Is there an official Helm chart for Fineract?

No. The Helm section of the official documentation says "TBD" and the repository contains no chart. Community charts exist on Artifact Hub; none is published by the Apache Fineract project.

What are the default Fineract login credentials?

Username mifos, password password, tenant default. They are identical on every install and published in the README, so change them immediately with POST /fineract-provider/api/v1/users/1/pwd or in the web app.

Can I run Fineract on MySQL or MariaDB?

You can, but both are deprecated, the official image does not include their JDBC drivers, and the accepted FSIP-9 proposal is to support PostgreSQL only. For a new install, use PostgreSQL.

Do I need Java installed to run Fineract in Docker?

Not to run it: the image ships with a Java 25 runtime. You need a JDK 25 only to build the image yourself, which at the moment is how you get a 1.16.1 image.

Skip the ops. Run managed Apache Fineract.

Finecko runs managed Apache Fineract for you - the Finecko Hub, the right topology, connection pooling, backups, TLS, patching, and on-call. You get the open-source core without the operations, and the free plan is a full environment to try with no credit card.