Installation Guide · Step 4

Install Mifos X on Ubuntu

Prepare an Ubuntu server for Apache Fineract and the Mifos Web App using controlled Docker images, persistent storage, Nginx, HTTPS, backups and monitoring.

Start installation Security checklist

Recommended design

Production architecture

Nginx reverse proxy

Terminates HTTPS and routes frontend and API traffic securely.

Mifos Web App

Provides the browser-based user interface used by operational teams.

Apache Fineract

Provides lending, savings, accounting, reporting and REST API services.

Database

Stores tenants, customers, products, loans, transactions and accounting data.

Backup and monitoring

Protects business data and alerts the operations team when services fail.

Before installation

Prerequisites

✓Ubuntu 24.04 LTS or another tested supported Linux release
✓A non-root administrative user with sudo access
✓A domain or subdomain pointing to the server
✓A tested Apache Fineract release or image tag
✓A tested Mifos Web App release or commit
✓A supported database version
✓At least 4 CPU cores and 16 GB RAM for an initial small production setup
✓Backup storage separate from the application server

Step-by-step

Prepare the Ubuntu server

Update Ubuntu

Apply available package and security updates before installing application dependencies.

sudo apt update
sudo apt upgrade -y
sudo reboot

Create a dedicated deployment user

Avoid operating the application permanently as the root user.

sudo adduser mifos
sudo usermod -aG sudo mifos

Install required utilities

Install Git, curl, certificate utilities, firewall tools and supporting packages.

sudo apt install -y \
  ca-certificates \
  curl \
  git \
  gnupg \
  nginx \
  ufw \
  unzip

Install Docker Engine

Use Docker's signed Ubuntu repository instead of an uncontrolled installation script.

sudo install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update

sudo apt install -y \
  docker-ce \
  docker-ce-cli \
  containerd.io \
  docker-buildx-plugin \
  docker-compose-plugin

Allow the deployment user to run Docker

Add the dedicated Mifos user to the Docker group and start a fresh login session.

sudo usermod -aG docker mifos
sudo systemctl enable --now docker

Create production directories

Separate application files, secrets, persistent data, logs and backups.

sudo mkdir -p /opt/mifos/{app,config,data,logs,backups}
sudo chown -R mifos:mifos /opt/mifos
sudo chmod 750 /opt/mifos

Protect the environment file

Store database and application secrets outside the source-code repository.

sudo -u mifos touch /opt/mifos/config/production.env
sudo chmod 600 /opt/mifos/config/production.env

Create the Compose deployment

Use fixed, reviewed image tags. Never leave production images on a floating latest tag.

sudo -u mifos nano /opt/mifos/app/docker-compose.yml

Validate and start the services

Review the resolved Compose configuration before starting containers.

cd /opt/mifos/app

docker compose --env-file ../config/production.env config

docker compose --env-file ../config/production.env pull

docker compose --env-file ../config/production.env up -d

Check service health

Review container state and application logs before exposing the platform publicly.

cd /opt/mifos/app

docker compose ps

docker compose logs --tail=200 fineract

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

Network protection

Configure the firewall

sudo ufw default deny incoming
sudo ufw default allow outgoing

sudo ufw allow OpenSSH
sudo ufw allow "Nginx Full"

sudo ufw enable
sudo ufw status verbose

Never enable a firewall remotely before allowing SSH. Doing so can lock you out of the server.

Production readiness

Security and operations checklist

✓Use fixed backend, frontend and database versions
✓Use strong unique database and application passwords
✓Keep secrets outside Git and application source code
✓Restrict database access to the private Docker network
✓Expose only SSH, HTTP and HTTPS through the firewall
✓Disable direct root SSH login
✓Use SSH keys instead of password-only administration
✓Configure automatic security updates carefully
✓Create daily encrypted database backups
✓Copy backups to a separate server or storage account
✓Test database restoration before go-live
✓Configure uptime, resource and log monitoring

Production implementation

Need a secure Mifos production deployment?

MifosX provides Apache Fineract deployment, database setup, Mifos Web App configuration, SSL, backups, monitoring, migration, testing and production support.

Talk to a Mifos expert Talk to a MifosX expert

← Previous: Docker installation Next: Apache Fineract backend setup →