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. This guide is for developers who want a disposable local environment for integration development and testing.

---

Prerequisites

• Docker and Docker Compose installed
• At least 4 GB RAM available for Docker
• Ports 8443 and 3306 (or 5432 for PostgreSQL) free on your machine

---

Quick Start with Docker Compose

Create a docker-compose.yml file:

version: "3.8"

services:
  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: mysql
    volumes:
      - fineract-db:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-pmysql"]
      interval: 10s
      timeout: 5s
      retries: 10

  fineract:
    image: apache/fineract:latest
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "8443:8443"
    environment:
      FINERACT_HIKARI_JDBC_URL: jdbc:mariadb://db:3306/fineract_tenants
      FINERACT_HIKARI_USERNAME: root
      FINERACT_HIKARI_PASSWORD: mysql
      FINERACT_DEFAULT_TENANTDB_HOSTNAME: db
      FINERACT_DEFAULT_TENANTDB_PORT: 3306
      FINERACT_DEFAULT_TENANTDB_UID: root
      FINERACT_DEFAULT_TENANTDB_PWD: mysql
      FINERACT_DEFAULT_TENANTDB_NAME: fineract_default
      FINERACT_DEFAULT_TENANTDB_TIMEZONE: UTC
      FINERACT_NODE_ID: 1
      FINERACT_REMOTE_JOB_MESSAGE_HANDLER_SPRING_EVENTS_ENABLED: "true"

volumes:
  fineract-db:

Start everything:

docker compose up -d

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

docker compose logs -f fineract

Look for a line containing Started App in - 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:

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

Expected response:

{"status":"UP"}

Test the API with default credentials:

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

Field	Value
Username	mifos
Password	password
Tenant ID	default
Base URL	https://localhost:8443/fineract-provider/api/v1
Swagger UI	https://localhost:8443/fineract-provider/api/v1/swagger-ui/index.html

Change the default password immediately after first login via:

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

---

Using a Specific Fineract Version

Replace apache/fineract:latest with a specific version tag to pin your local environment:

image: apache/fineract:1.10.1

Available tags are listed at hub.docker.com/r/apache/fineract.

Match your Finecko version

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

GET /fineract-provider/api/v1/version

Use the same tag locally to ensure API compatibility.

---

PostgreSQL Alternative

If you prefer PostgreSQL over MySQL:

services:
  db:
    image: postgres:15
    environment:
      POSTGRES_USER: fineract
      POSTGRES_PASSWORD: fineract
    volumes:
      - fineract-db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U fineract"]
      interval: 10s
      timeout: 5s
      retries: 10

  fineract:
    image: apache/fineract:latest
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "8443:8443"
    environment:
      FINERACT_HIKARI_DRIVER_SOURCE_CLASS_NAME: org.postgresql.ds.PGSimpleDataSource
      FINERACT_HIKARI_JDBC_URL: jdbc:postgresql://db:5432/fineract_tenants
      FINERACT_HIKARI_USERNAME: fineract
      FINERACT_HIKARI_PASSWORD: fineract
      FINERACT_DEFAULT_TENANTDB_HOSTNAME: db
      FINERACT_DEFAULT_TENANTDB_PORT: 5432
      FINERACT_DEFAULT_TENANTDB_UID: fineract
      FINERACT_DEFAULT_TENANTDB_PWD: fineract
      FINERACT_DEFAULT_TENANTDB_NAME: fineract_default
      FINERACT_DEFAULT_TENANTDB_CONN_PARAMS: "sslmode=disable"
      FINERACT_NODE_ID: 1
      FINERACT_REMOTE_JOB_MESSAGE_HANDLER_SPRING_EVENTS_ENABLED: "true"

---

Adding the Mifos X Web App

To also run the community frontend locally, add it as a service:

  webapp:
    image: openmf/community-app:latest
    ports:
      - "9090:80"
    environment:
      FINERACT_API_URL: https://localhost:8443
      FINERACT_PLATFORM_TENANT_IDENTIFIER: default

Access the UI at http://localhost:9090. Point it at https://localhost:8443 and log in with mifos / password.

---

Stopping and Resetting

# Stop containers (data preserved in the volume)
docker compose down

# Stop and delete all data (full reset)
docker compose down -v

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

---

Common Issues

Problem	Cause	Fix
Fineract starts but immediately restarts	DB not ready when Fineract started	The healthcheck handles this - wait for the db service to pass healthcheck before Fineract starts
SSL connection error on curl	Self-signed cert	Add -k to curl commands for local dev
400 Bad Request on every API call	Missing tenant header	Add -H "Fineract-Platform-TenantId: default"
Very slow startup	Low Docker memory	Allocate at least 4 GB RAM to Docker Desktop
Fineract logs show Liquibase lock error	Previous run crashed mid-migration	Run the SQL to clear the lock - see Troubleshooting

---

Next Steps

Once your local environment is running:

• Explore the API using the Swagger UI
• Follow the Getting Started guide to create your first office, client, and loan
• When ready, point your integration at your Finecko managed instance instead of localhost