Apache Fineract — Local Setup Guide

O

Qubits of DPK

March 20, 2026

Core Open Source

Step 1 — Prerequisites

Install these first:
bash
QUBITS OF DPK
1# Java 21 (required)
2brew install openjdk@21
3echo 'export JAVA_HOME=/opt/homebrew/opt/openjdk@21' >> ~/.zshrc
4source ~/.zshrc
5java -version  # should show 21
6
7# Docker Desktop — download from https://docker.com/products/docker-desktop
8# Verify after installing:
9docker --version
10docker compose version

Step 2 — Clone the Repo

bash
QUBITS OF DPK
1git clone https://github.com/apache/fineract.git
2cd fineract

Step 3 — Start the Database (Docker)

Fineract needs MariaDB running before the app starts:
bash
QUBITS OF DPK
1# From the root of the fineract folder:
2docker compose -f docker-compose-mariadb.yml up -d mariadb
Wait ~20 seconds, then verify:
bash
QUBITS OF DPK
1docker ps   # should show fineract-mariadb container as "Up"

Step 4 — Build the Project

bash
QUBITS OF DPK
1# Skip tests for a fast first build (~5-8 min)
2./gradlew :fineract-provider:bootJar -x test
You'll see BUILD SUCCESSFUL at the end.

Step 5 — Run the Application

bash
QUBITS OF DPK
1./gradlew :fineract-provider:bootRun \
2  -Dfineract.node-id=1 \
3  -Dspring.datasource.url=jdbc:mariadb://localhost:3306/fineract_tenants \
4  -Dspring.datasource.username=root \
5  -Dspring.datasource.password=mysql
Wait for this log line:
plain text
QUBITS OF DPK
1Started FineractApplication in XX.XXX seconds

Step 6 — Verify in Postman

  1. #
    Disable SSL verification in Postman (Settings ️ → SSL certificate verification → OFF) — Fineract uses a self-signed cert locally
  2. #
    Hit [Health] Server Health Check → expect {"status":"UP"}
  3. #
    Hit [Health] API Alive — Get Head Office → expect 200 with office data

Default Credentials

Common Problems & Fixes

Quick Restart (after first setup)

bash
QUBITS OF DPK
1# Terminal 1 — DB
2docker compose -f docker-compose.yml up -d mariadb
3
4# Terminal 2 — App
5./gradlew :fineract-provider:bootRun
That's it — once the DB is up and the app starts, all 28 Postman requests will work.