Installation Guide · Step 5

Apache Fineract backend setup

Configure the Apache Fineract core banking and lending backend, database connection, tenants, application environment, health checks, logs and production controls.

Start backend setup Verification checklist

Core component

What Apache Fineract provides

Apache Fineract provides the backend services used for clients, groups, offices, loan products, savings, transactions, accounting, reports, scheduled jobs and integrations. The Mifos Web App communicates with these services through REST APIs.

Client and group management

Loan and savings processing

Accounting and journal entries

Charges, penalties and transactions

Scheduled jobs and batch processing

REST APIs and integrations

Configuration

Environment values to document

Setting	Guidance
Database hostname	Use the internal Docker service name or private database hostname, not a publicly exposed address.
Database username	Create a dedicated application user with only the permissions required by Fineract.
Database password	Use a strong unique password stored in a protected secret or environment file.
Tenant identifier	Record the tenant ID used by the frontend, API clients and integrations.
Application port	Bind the backend privately and expose it through Nginx or another trusted reverse proxy.
Java memory	Set initial and maximum heap values based on server capacity and measured workload.

Step-by-step

Configure and start Apache Fineract

Select and record the Fineract version

Use a reviewed stable release or exact Git commit. Do not deploy an unrecorded moving branch.

git clone https://github.com/apache/fineract.git
cd fineract

git tag --sort=-version:refname | head -20
git checkout YOUR_REVIEWED_RELEASE_TAG

git rev-parse HEAD
git describe --tags --always

Review the selected release requirements

Check the release documentation and build files for required Java, Gradle and database versions.

sed -n '1,220p' README.md
grep -R "JavaVersion\|sourceCompatibility\|toolchain" -n build.gradle* fineract-provider/build.gradle* 2>/dev/null | head -40

Inspect Docker Compose configuration

Review all configured services, image tags, ports, volumes, health checks and environment variables.

find . -maxdepth 3 -type f -name "docker-compose*.yml" -print

docker compose config

Create a secure environment file

Keep passwords and deployment-specific values outside the source repository.

mkdir -p config/private

touch config/private/fineract.env
chmod 600 config/private/fineract.env

nano config/private/fineract.env

Validate database connectivity

Confirm that the selected database service is healthy before starting Apache Fineract.

docker compose up -d database

docker compose ps
docker compose logs --tail=200 database

Start Apache Fineract

Start the backend only after reviewing the resolved Compose configuration.

docker compose --env-file config/private/fineract.env config

docker compose --env-file config/private/fineract.env up -d

Monitor application startup

Watch for database connectivity, Liquibase migration, tenant initialization and Java startup errors.

docker compose logs -f fineract

Check the health endpoint

Verify that the backend is running before connecting the Mifos Web App.

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

Verify the REST API

Test an authenticated endpoint using the correct tenant header and deployment credentials.

curl -k \
  -u "YOUR_USERNAME:YOUR_PASSWORD" \
  -H "Fineract-Platform-TenantId: default" \
  -H "Accept: application/json" \
  "https://127.0.0.1:8443/fineract-provider/api/v1/offices"

Record the deployed configuration

Maintain a compatibility register for every development, staging and production environment.

docker compose ps
docker images
git rev-parse HEAD
java -version
docker --version
docker compose version

Validation

Backend verification checklist

✓Database container or service is healthy
✓Liquibase migrations completed without errors
✓Fineract health endpoint reports a healthy state
✓Tenant database is accessible
✓Authentication works using the correct tenant header
✓Office and client APIs return valid responses
✓Scheduled jobs are visible and correctly configured
✓Application logs contain no recurring errors
✓Database and application backups are configured
✓Backend port is not exposed publicly without protection

Troubleshooting

Common backend problems

Database connection refused

Check the database hostname, port, container network, credentials and service health.

Liquibase migration failure

Stop the deployment, preserve the database, inspect the failed migration and test recovery in staging.

Tenant not found

Verify the Fineract-Platform-TenantId header and tenant database configuration.

HTTP 401 or 403

Check credentials, authentication mode, roles, permissions and tenant headers.

OutOfMemoryError

Review Java heap settings, reports, scheduled jobs, available RAM and container resource limits.

Backend is healthy but Web App cannot connect

Check the frontend API URL, HTTPS certificate, reverse proxy, CORS and browser console errors.

MifosX Apache Fineract services

Need help configuring or customizing Fineract?

MifosX provides Apache Fineract implementation, customization, upgrades, integrations, database support, performance tuning, migration and production support.

Talk to a Mifos expert Talk to a MifosX expert

← Previous: Ubuntu installation Next: Mifos Web App installation →