Sign inSign up
fineract logo

upstreamyard/fineract

By upstreamyard

•Updated 17 days ago

Apache Fineract core banking: versioned releases, signed, multi-arch, non-root, MariaDB driver

Image
0

237

upstreamyard/fineract repository overview

upstreamyard logo

⁠Fineract Docker image (Apache Fineract 1.16)

Have any questions, feedback or need help (e.g. setup, hardened images, etc.)? Reach out to [email protected]⁠

Production-ready, multi-arch (amd64, arm64) and signed Apache Fineract Docker image, with a version tag for every Apache Fineract release, built from the signed Apache binary release. Fineract's own image has had no version tags since 1.12.1, and its latest tag is an unreleased development build. This image is secure by default: FINERACT_ADMIN_PASSWORD replaces the default mifos/password login, every container gets its own TLS certificate instead of the public built-in one, and it runs as non-root with a healthcheck. PostgreSQL and MariaDB drivers are included, document uploads work and persist in a volume, and the image runs as read, write or batch instance for high availability and scaling. Use it with Docker Compose, or on Kubernetes with our Fineract Helm chart⁠.

Community-maintained by upstreamyard. This is not an official Apache Fineract image. Apache Fineract is licensed under Apache-2.0 (see Licences⁠). Apache, Apache Fineract and Fineract are trademarks of the Apache Software Foundation.

RegistryImage
Docker Hubupstreamyard/fineract
GitHub Container Registryghcr.io/upstreamyard/fineract
TagFollowsJava
1.16.1, 1.16, latestApache Fineract 1.16.x, the current releaseEclipse Temurin 25

New Fineract releases are built within 24 hours of appearing on Apache's download server. Pin 1.16 to get patch releases automatically; pin 1.16.1 to control database migrations yourself.

⁠Why this Fineract image

Compared with Fineract's own apache/fineract image. We tested its latest tag on 2026-10-31.

apache/fineract:latestupstreamyard/fineract
Version tagsnone since 1.12.1 (Sept 2025); latest is 1.17.0-SNAPSHOT, the development branchevery release: 1.16.1, 1.16, latest
Built fromthe development branch, by Fineract's CIthe signed Apache binary release (SHA-512 and GPG checked)
Login mifos / passwordstays until you change itreplaced on the first start with FINERACT_ADMIN_PASSWORD
HTTPS certificatebuilt-in keystore whose private key is public (Fineract's source code)generated per container; or your PEM files (e.g. cert-manager), reloaded on renewal; or your own keystore
Document and image uploadsfail with HTTP 500 (ContentStoreException: /.fineract)stored in /var/lib/fineract (volume)
JVM options (-Duser.timezone=UTC, …)passed after the main class, so ignoredapplied
HeapJava default: 25% of the memory limit60% of the memory limit
MariaDB drivernot includedincluded (MariaDB Connector/J 3.5.11)
Healthchecknonebuilt in (readiness endpoint)
Runs asnobody (UID 65534)non-root UID 10001; read-only root filesystem supported
Signed, SBOM, provenancenocosign, SBOM, SLSA provenance
Helm chartnoneupstreamyard/fineract⁠

Both stop cleanly on SIGTERM within about 2 seconds.

⁠At a glance

Ports8443 HTTPS (default), 8080 HTTP with FINERACT_SERVER_SSL_ENABLED=false
APIhttps://<host>:8443/fineract-provider/api/v1, header Fineract-Platform-TenantId: default, HTTP basic auth
Probes/fineract-provider/actuator/health/liveness and /readiness; the image's HEALTHCHECK uses readiness
MetricsPrometheus: /fineract-provider/actuator/prometheus (no login, same port)
RequiresPostgreSQL (tested: 18), MariaDB (tested: 11.8) or MySQL (tested: 8.4, driver not included). Two databases must exist: fineract_tenants and fineract_default
Storage/var/lib/fineract: uploaded documents and images. Mount a volume, or use S3
Configenvironment variables (FINERACT_*)
Runs asUID/GID 10001. With a read-only root filesystem, /tmp must be writable
First startabout 30–150 s: Fineract creates its tables (Liquibase)
ShutdownSIGTERM stops Fineract cleanly (exit code 143)

AI agents and coding assistants: read AGENTS.md⁠ for deployment rules, and llms.txt⁠ for an index of all docs.

⁠Quick start: run Fineract in Docker

docker-compose.yml⁠ starts Fineract with PostgreSQL 18. Change the change-me values, then:

docker compose up -d
docker compose logs -f fineract   # wait for "replaced the default password of user mifos"
curl -k -u 'mifos:Change-me-4dm1n!' -H 'Fineract-Platform-TenantId: default' \
  https://localhost:8443/fineract-provider/api/v1/offices

The answer lists the "Head Office". Swagger UI: https://localhost:8443/fineract-provider/swagger-ui/index.html⁠. Fineract is an API server; for a web UI, run the separate Mifos X web app⁠ against it.

MariaDB instead: examples/mariadb/docker-compose.yml⁠.

⁠Configuration

⁠Environment variables

The most important settings. All other Fineract settings work as documented in Fineract's configuration reference⁠ (FINERACT_* variables).

VariableDefaultDescription
FINERACT_HIKARI_JDBC_URLjdbc:postgresql://localhost:5432/fineract_tenantsTenant store database
FINERACT_HIKARI_USERNAME, FINERACT_HIKARI_PASSWORDroot, postgresIts login
FINERACT_HIKARI_DRIVER_SOURCE_CLASS_NAMEorg.postgresql.Driverorg.mariadb.jdbc.Driver for MariaDB
FINERACT_DEFAULT_TENANTDB_HOSTNAME, _PORT, _NAMElocalhost, 5432, fineract_defaultDatabase of the default tenant
FINERACT_DEFAULT_TENANTDB_UID, _PWDroot, postgresIts login
FINERACT_DEFAULT_TENANTDB_MASTER_PASSWORDfineractEncrypts the tenant's database password in the tenant store. Set it before the first start and never change it: with another value Fineract exits with Invalid master password
FINERACT_DEFAULT_TENANTDB_TIMEZONEAsia/KolkataTime zone of the default tenant, stored on the first start
FINERACT_ADMIN_PASSWORD–Replaces the password of user mifos once Fineract is ready, but only while it is still password (write instances only). Must meet Fineract's password policy: 12–50 characters with upper and lower case, a digit and a special character, no spaces, no character twice in a row
FINERACT_SERVER_SSL_ENABLEDtruefalse: plain HTTP, e.g. behind a TLS-terminating proxy
FINERACT_SERVER_PORT8443, or 8080 without TLSListening port
FINERACT_SERVER_SSL_CERTIFICATE, _CERTIFICATE_PRIVATE_KEY–PEM certificate and key files, e.g. from a Kubernetes TLS Secret. Reloaded when the files change (this image)
FINERACT_SERVER_SSL_KEY_STORE, _PASSWORDgeneratedYour own keystore (PKCS12 or JKS), e.g. /etc/fineract/tls/keystore.p12
FINERACT_MODE_READ_ENABLED, _WRITE_ENABLED, _BATCH_MANAGER_ENABLED, _BATCH_WORKER_ENABLEDtrueInstance type, see Scaling⁠
FINERACT_LIQUIBASE_ENABLEDtrueDatabase migrations at start
FINERACT_NODE_ID1Scheduled jobs are stored for node 1: keep 1 on the instance that runs jobs
FINERACT_CONTENT_FILESYSTEM_ROOT_FOLDER/var/lib/fineractUploaded documents and images (Fineract's default ~/.fineract)
FINERACT_LOGGING_JSON_ENABLEDfalsetrue: one JSON object per log line
FINERACT_LOGGING_LEVELINFOLog level of org.apache.fineract
JAVA_OPTS_MEMORY-XX:InitialRAMPercentage=25.0 -XX:MaxRAMPercentage=60.0Heap options
JAVA_OPTS–Extra Java options, added after ours

Every FINERACT_* variable also has a _FILE variant that reads the value from a file, e.g. FINERACT_HIKARI_PASSWORD_FILE=/run/secrets/db-password for Docker or Kubernetes secrets.

Set a memory limit of at least 2 GiB: right after the start Fineract uses about 1.5 GiB.

Each instance holds two database connection pools: the tenant store (up to 10 connections) and the tenant database (up to 40, a default stored when the tenant is created). Idle, an instance keeps 8 connections open. Cap the tenant pool with FINERACT_CONFIG_MAX_POOL_SIZE and size the database's max_connections for all instances.

⁠Databases

Fineract needs two databases before its first start: the tenant store (fineract_tenants) and the default tenant (fineract_default), both owned by the database user Fineract logs in with. It creates all tables itself. The Compose files above create both databases with an init script.

  • PostgreSQL: the default. Tested with PostgreSQL 18.
  • MariaDB: driver included. Start MariaDB with --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci --innodb-snapshot-isolation=OFF (Fineract's own MariaDB settings), set FINERACT_HIKARI_DRIVER_SOURCE_CLASS_NAME=org.mariadb.jdbc.Driver, a jdbc:mariadb:// URL and FINERACT_DEFAULT_TENANTDB_PORT=3306. Tested with MariaDB 11.8.
  • MySQL: the MySQL driver is GPL-licensed and not included. Mount MySQL Connector/J⁠ into /app/plugins (see Extending⁠) and use com.mysql.cj.jdbc.Driver with a jdbc:mysql:// URL. Tested with MySQL 8.4 and Connector/J 9.7.0.
⁠HTTPS

Fineract serves HTTPS on port 8443 by default. Its built-in keystore is the same for every installation and its private key is public, so this image generates a self-signed certificate for each container at start instead (EC P-256, valid for localhost, 127.0.0.1 and the container hostname). Clients still have to accept a self-signed certificate. For production, either:

  • mount a certificate and key in PEM format, e.g. a Kubernetes TLS Secret from cert-manager, and set FINERACT_SERVER_SSL_CERTIFICATE and FINERACT_SERVER_SSL_CERTIFICATE_PRIVATE_KEY to the two file paths. Fineract picks up a renewed certificate within seconds, without a restart (tested with RSA keys in PKCS#1 format, cert-manager's default);
  • mount your own keystore and set FINERACT_SERVER_SSL_KEY_STORE and FINERACT_SERVER_SSL_KEY_STORE_PASSWORD; or
  • terminate TLS in front of Fineract (load balancer, ingress) and set FINERACT_SERVER_SSL_ENABLED=false.

Fineract's documentation lists FINERACT_SERVER_SSL_PROTOCOLS and FINERACT_SERVER_SSL_CIPHERS, but Fineract 1.16.1 ignores them.

⁠Admin password

Every new Fineract tenant has a superuser mifos with the password password. With FINERACT_ADMIN_PASSWORD, the container logs in as mifos once Fineract is ready and sets the new password. Until then, which takes a few seconds after the readiness probe succeeds, the old password works. Once the password has changed, the variable has no further effect, so change it later through Fineract's API or UI. Without the variable, the container logs a warning on every start while mifos still has the default password.

⁠Scaling and high availability

Fineract's instance types let one database serve several containers:

InstanceSettingsTested behaviour
All in one (default)–everything
ReadFINERACT_MODE_WRITE_ENABLED=false, FINERACT_MODE_BATCH_MANAGER_ENABLED=false, FINERACT_MODE_BATCH_WORKER_ENABLED=falseGET answered, writes and job APIs return 405
BatchFINERACT_MODE_READ_ENABLED=false, FINERACT_MODE_WRITE_ENABLED=falsejob APIs answered, other APIs return 405
  • Only one instance should run database migrations: run the image once with SPRING_PROFILES_ACTIVE=liquibase-only (migrates and exits with code 0), and start the servers with FINERACT_LIQUIBASE_ENABLED=false.
  • Fineract's documentation names these variables FINERACT_READ_MODE_ENABLED etc.; Fineract 1.16.1 reads FINERACT_MODE_READ_ENABLED etc., as shown above.
  • Without read replica settings (FINERACT_DEFAULT_TENANTDB_RO_*), a read instance uses the tenant's normal database connection (tested). We haven't tested read replicas.
  • Separate batch manager and worker instances exchange work through JMS or Kafka (FINERACT_REMOTE_JOB_MESSAGE_HANDLER_*); we haven't tested that split.
  • Uploaded documents must be on storage that all write instances share. Fineract can also store them in S3 (FINERACT_CONTENT_S3_*); we haven't tested that.

⁠Kubernetes and Helm: Fineract Helm chart

The recommended way to run Fineract on Kubernetes is our Helm chart (upstreamyard/helm-charts⁠): a migration Job, write, read and batch instances, Secrets for all passwords and a ServiceMonitor.

helm repo add upstreamyard https://upstreamyard.github.io/helm-charts
helm install fineract upstreamyard/fineract -f my-values.yaml

Running the image yourself:

  1. Run migrations in a Job with SPRING_PROFILES_ACTIVE=liquibase-only, and set FINERACT_LIQUIBASE_ENABLED=false on the Deployments.
  2. Pass passwords from a Secret (env.valueFrom.secretKeyRef or the _FILE variants).
  3. Probes: httpGet on /fineract-provider/actuator/health/liveness and /readiness, port 8443 with scheme: HTTPS, or 8080 with FINERACT_SERVER_SSL_ENABLED=false. Use a startupProbe that allows a few minutes.
  4. Set a memory limit of at least 2 GiB; the heap is 60% of it.
  5. The container works with runAsNonRoot: true, readOnlyRootFilesystem: true (plus an emptyDir at /tmp) and all capabilities dropped.

⁠Migrating to this image

From apache/fineract: the environment variables are the same, so keep them.

  • The container runs as UID 10001 instead of nobody. Files you mount must be readable by it.
  • Documents now go to /var/lib/fineract. In Fineract's image they could not be stored at all.
  • If you ran apache/fineract:latest: your database already contains changes from Fineract's development branch (15 more migrations than 1.16.1 on 2026-10-31). In our test, 1.16.1 started on such a database and answered API calls, but Fineract doesn't support going back to an older version. Try it on a copy of your database first, or wait for the next release.

⁠Extending the image

Jars in /app/plugins are added to Fineract's classpath, e.g. JDBC drivers or Fineract plugins:

docker run -v "$PWD/plugins:/app/plugins:ro" ... upstreamyard/fineract:1.16

Or build your own image:

FROM upstreamyard/fineract:1.16
ADD --chmod=644 https://repo1.maven.org/maven2/com/mysql/mysql-connector-j/9.7.0/mysql-connector-j-9.7.0.jar /app/plugins/

⁠FAQ

How do I run Fineract in Docker? Use the quick start⁠: Fineract plus PostgreSQL in one Compose file.

Is there a Helm chart for Fineract? Yes: upstreamyard/fineract⁠. Fineract's own documentation has a "Helm Charts" page that says "TBD".

Which tag should I use? 1.16 for the current release with its patch releases. Fineract's own apache/fineract:latest is a development build, not a release.

What is the default Fineract login? User mifos, password password, tenant default. Set FINERACT_ADMIN_PASSWORD so it is replaced on the first start.

Why do I get Invalid master password? FINERACT_DEFAULT_TENANTDB_MASTER_PASSWORD differs from the value used on the first start. Set the original value again.

How do I run Fineract highly available? Several write instances on one database, migrations in a separate run, documents in S3 or on shared storage; see Scaling⁠ and the Helm chart.

How do I monitor Fineract with Prometheus? Scrape /fineract-provider/actuator/prometheus on the API port.

Where is the web UI? Fineract is the API server. The Mifos X web app⁠ is a separate project that runs in front of it.

⁠Verifying images

Images are signed keylessly with cosign⁠ and include an SBOM and SLSA provenance:

cosign verify upstreamyard/fineract:1.16 \
  --certificate-identity-regexp '^https://github.com/upstreamyard/fineract/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
docker buildx imagetools inspect upstreamyard/fineract:1.16 --format '{{ json .SBOM }}'

⁠How it's built

.github/workflows/build.yml⁠ finds the release Apache currently lists on its download server. scripts/fetch-release.sh⁠ downloads the official binary release, checks its SHA-512 and its GPG signature against the Fineract KEYS file, and takes the executable fineract-provider jar and the licence files from it. CI then builds the Dockerfile⁠ for amd64 and arm64.

  • Java: Eclipse Temurin JRE, the version the release was compiled for (Java 25 for 1.16). Base: Ubuntu 24.04.
  • Added: MariaDB Connector/J 3.5.11 (Maven Central, pinned by SHA-256), tini, curl.
  • Changed: nothing inside Fineract. The entrypoint⁠ sets Java options, generates the TLS certificate and sets the admin password.
  • Testing: before publishing, scripts/smoke-test.sh⁠ checks:
    • the first start on PostgreSQL 18 and on MariaDB 11.8;
    • the admin password and the generated certificate;
    • a document upload that survives a restart, Prometheus metrics and a clean stop;
    • a liquibase-only run, then HTTP, _FILE secrets and a read-only root filesystem;
    • read and batch instances, and a PEM certificate that is replaced while Fineract runs;
    • that a changed master password is refused.

⁠Licences

ComponentLicenceLicence text in the imageSource code
Apache FineractApache-2.0/licenses/fineract/ (LICENSE, NOTICE and the licences of its bundled libraries)apache/fineract⁠ at tag <version>
MariaDB Connector/JLGPL-2.1-or-later/licenses/mariadb-jdbc/mariadb-corporation/mariadb-connector-j⁠
Ubuntu packages, Eclipse Temurinvarious, incl. GPL/usr/share/doc/*/copyright, /opt/java/openjdk/legal/Ubuntu and Adoptium source archives
Our packaging (Dockerfile, scripts)Apache-2.0–this repository

⁠Support

Issues with the image: open an issue here⁠. Questions about using Fineract: Fineract's mailing lists and chat⁠.

Tag summary

Content type

Image

Digest

sha256:82a647193…

Size

304.1 MB

Last updated

17 days ago

docker pull upstreamyard/fineract