Installation Guide · Step 3

Install Mifos X using Docker

Use Docker Compose to run Apache Fineract, its database and supporting services in a repeatable local environment. This method is suitable for learning, demonstrations, development and initial testing.

Start installation Troubleshooting

Before you begin

Prerequisites

Confirm that your computer meets the following basic requirements.

64-bit Windows, Linux or macOS computer
At least 4 CPU cores recommended
At least 8 GB RAM recommended
20 GB or more free disk space
Docker Engine or Docker Desktop
Docker Compose v2
Git command-line client
Internet connection for downloading images

Important version note

Record the exact source version

The default repository branch changes over time. For a repeatable installation, use a reviewed release tag or commit and record it in your deployment register.

Record source version

git branch --show-current
git rev-parse HEAD
git describe --tags --always

Step-by-step

Start Apache Fineract with Docker

Run each step in sequence and verify the expected result before continuing.

Confirm Docker is installed

Verify that Docker Engine and Docker Compose are available before downloading the source code.

docker --version
docker compose version

Expected result: Both commands should return installed version information without an error.

Create a working directory

Keep the Apache Fineract installation in a separate directory so it can be upgraded or removed safely.

mkdir -p ~/mifos-docker
cd ~/mifos-docker

Expected result: Your terminal should now be inside the mifos-docker directory.

Clone Apache Fineract

Download the official Apache Fineract repository. For production or repeatable testing, replace the development branch with a reviewed release tag.

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

Expected result: A new fineract directory should be created containing the source code and Docker Compose files.

Review the available Docker files

The repository contains multiple Docker Compose files for different database, frontend and development combinations.

ls -1 docker-compose*.yml
find config/docker/compose -maxdepth 1 -type f -name "*.yml" -print

Expected result: You should see Docker Compose files for Fineract and supporting services.

Start the Fineract stack

Use the Compose file documented for the selected version. The exact services may differ between releases.

docker compose up -d

Expected result: Docker should create and start the configured database and Apache Fineract services.

Check container status

Confirm that the containers are running and review any unhealthy or restarting service.

docker compose ps

Expected result: The required database and Fineract containers should display a running or healthy state.

Watch the startup logs

The first startup may take several minutes because the database and Liquibase migrations must complete.

docker compose logs -f

Expected result: Wait until the application reports that it has started successfully. Press Ctrl+C to stop watching logs without stopping the containers.

Verify the backend health

Test the Fineract health endpoint. Depending on the selected Compose file, the exposed protocol or port may differ.

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

Expected result: A healthy installation should return a response containing a status such as "UP".

Container management

Useful Docker commands

View container status

docker compose ps

View recent logs

docker compose logs --tail=200

Restart services

docker compose restart

Stop services

docker compose down

Stop and remove local volumes

docker compose down -v

The docker compose down -v command deletes attached local volumes and may permanently remove your test database.

Web interface

Add the Mifos Web App

Apache Fineract is the backend API. Users normally access it through the Mifos Web App. The official repositories include Docker configurations for running the frontend with Fineract.

Inspect frontend Compose file

ls -1 docker-compose-web-app.yml
sed -n '1,220p' docker-compose-web-app.yml

Review the image name, API base URL, exposed port and tenant settings before starting the frontend. These values may differ between releases.

Continue to the Mifos Web App guide

Common problems

Docker installation troubleshooting

Docker command not found

Install Docker Engine or Docker Desktop, restart the terminal and run docker --version again.

Permission denied while accessing Docker

On Linux, run Docker using sudo or add the user to the docker group, then sign out and sign in again.

Port 8443 is already in use

Identify the application using the port or modify the host-port mapping in the Docker Compose file.

Database container is unhealthy

Review database logs, environment variables, passwords, storage permissions and available disk space.

Fineract keeps restarting

Review the Fineract logs for database connectivity, Liquibase, Java memory or configuration errors.

Health endpoint does not respond

Wait for startup and migrations to complete, then confirm the exposed port using docker compose ps.

Production warning

Do not move the demonstration stack directly into production

Production deployment requires controlled versions, secrets, backups, monitoring, security hardening, persistent storage, recovery planning and tested upgrade procedures.

Do not use floating latest image tags in production.
Do not store production passwords directly in committed Compose files.
Do not expose database ports publicly.
Do not run without persistent database storage.
Do not rely on a single local database backup.
Do not upgrade containers before testing database migrations.
Do not use the default demonstration credentials in production.

← Previous: System requirements Next: Ubuntu production installation →