Skip to content

Running Apache Fineract Locally ​

If you are building an integration, custom UI, or plugin against the Fineract API, you may want a local environment to develop and test against before connecting to your Finecko-managed instance.

This guide covers the quickest path to a working local Fineract setup using Docker Compose.

Finecko customers

You do not need a local setup to use Finecko. Your managed instance is ready to use via the API and the Mifos web app, which every Finecko plan includes. This guide is for developers who want a disposable local environment for integration development and testing.


Prerequisites ​

  • Docker and Docker Compose installed
  • Git and JDK 25 to build the Fineract image (Fineract 1.16.1 requires Java 25)
  • At least 4 GB RAM available for Docker
  • Ports 8443 and 5432 free on your machine

Build the Fineract Image ​

Do not use apache/fineract:latest from Docker Hub for a release setup: it is the same image as the develop tag, a continuous build of the development branch. The newest release tag on Docker Hub is 1.12.1, so there is no published image for the current release (1.16.1). Build it from the release tag instead:

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

This builds a local image named fineract:latest. Run the remaining commands from the same fineract directory.


Quick Start with Docker Compose ​

The release includes Docker Compose files. Start PostgreSQL and Fineract with:

bash
docker compose -f docker-compose-postgresql.yml up -d

This starts a PostgreSQL container, creates the fineract_tenants and fineract_default databases with an init script, and runs the fineract:latest image you just built. The connection settings are in config/docker/env/fineract-postgresql.env; each FINERACT_* variable is described in the Environment Variables Reference.

Local use only

These compose files enable the test Spring profile and use fixed passwords. They are for trying Fineract out, not for production.

Wait about 60-90 seconds for Fineract to complete its Liquibase migrations on first start. Watch the logs:

bash
docker compose -f docker-compose-postgresql.yml logs -f fineract

Look for the APACHE FINERACT IS READY banner - that signals the server is ready.


Verifying the Setup ​

Once started, Fineract is available at https://localhost:8443. The self-signed certificate will trigger a browser security warning - accept it for local development.

Test with a basic health check:

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

Expected response:

json
{"status":"UP","groups":["liveness","readiness"]}

The same Actuator endpoints are what you would alert on in production; Monitoring & Observability lists the metrics worth watching.

Test the API with default credentials:

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

This should return the default office (Head Office) as a JSON array.


Default Credentials ​

FieldValue
Usernamemifos
Passwordpassword
Tenant IDdefault
Base URLhttps://localhost:8443/fineract-provider/api/v1
Swagger UIhttps://localhost:8443/fineract-provider/swagger-ui/index.html

Change the default password immediately after first login via:

bash
PUT /fineract-provider/api/v1/users/{userId}

The default tenant comes from the FINERACT_DEFAULT_TENANTDB_* variables. To add more tenants to the local stack, follow Multi-Tenancy Configuration.


Using a Specific Fineract Version ​

To run another release, clone its tag instead of 1.16.1 and build the image the same way (docker-compose-postgresql.yml is in the release tags from 1.8.0 on). Older releases build with an older JDK: Java 17 for Fineract 1.6 to 1.11, Java 21 for 1.12 to 1.15.

Docker Hub has published release images only for 1.10.1, 1.11.0, 1.12.0 and 1.12.1 (see hub.docker.com/r/apache/fineract). For those versions you can pull apache/fineract:<version> instead of building it; check which image name that release's compose files expect.

Match your Finecko version

Check which Fineract version your Finecko instance is running via the version endpoint:

bash
GET /fineract-provider/api/v1/version

Use the same tag locally to ensure API compatibility.

If you restore a database from Fineract 1.5 or older into a newer image, its schema history is still managed by Flyway; follow Flyway to Liquibase Migration before starting the container.


MariaDB and MySQL ​

The Fineract image contains only the PostgreSQL JDBC driver: the MariaDB and MySQL drivers are left out for licensing reasons, and upstream marks both databases as deprecated. If you must test against them, add the driver to your own image and override the database settings as the Fineract README describes.


Adding the Mifos X Web App ​

To also run the Mifos X web app locally, start its container next to Fineract (openmf/web-app:master is the image Fineract's own docker-compose-web-app.yml uses):

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

Open https://localhost:8443 once in your browser and accept the self-signed certificate, then open http://localhost:4200 and log in with mifos / password. On Finecko you do not need this: the Mifos web app is hosted for you on every plan. UI options compares the available frontends.


Stopping and Resetting ​

bash
# Stop containers (data kept for the next start)
docker compose -f docker-compose-postgresql.yml stop

# Remove containers and all data (full reset)
docker compose -f docker-compose-postgresql.yml down -v

Deleting the volume forces Fineract to re-run all Liquibase migrations on the next start, giving you a clean database.


Common Issues ​

ProblemCauseFix
Fineract starts but immediately restartsDB not ready when Fineract startedThe healthcheck handles this - wait for the db service to pass healthcheck before Fineract starts
SSL connection error on curlSelf-signed certAdd -k to curl commands for local dev
400 Bad Request on every API callMissing tenant headerAdd -H "Fineract-Platform-TenantId: default"
Very slow startupLow Docker memoryAllocate at least 4 GB RAM to Docker Desktop
Fineract logs show Liquibase lock errorPrevious run crashed mid-migrationRun the SQL to clear the lock - see Troubleshooting

Next Steps ​

Once your local environment is running: