Apache Fineract on Ubuntu 24.04 on Azure User Guide

Overview

Apache Fineract is an open source core banking platform for financial inclusion. It provides a robust, secure REST API for managing clients, accounts, loans, savings and the general ledger, and is the engine behind the Mifos community of microfinance applications. The cloudimg image installs Apache Fineract 1.10.1 as a Spring Boot application (fineract-provider.jar) on OpenJDK 17, serving its REST API and Swagger UI over HTTPS on 127.0.0.1:8443, backed by MariaDB on a dedicated Azure data disk, and fronted by an nginx reverse proxy on TCP 80. A unique administrator password is generated on the first boot of every VM. Backed by 24/7 cloudimg support.

What is included:

• Apache Fineract 1.10.1 provider (fineract-provider.jar) on OpenJDK 17
• The Fineract REST API and the built in Swagger UI API console
• MariaDB holding the fineract_tenants and fineract_default schemas, populated by Fineract's Liquibase migrations
• A dedicated Azure data disk at /var/lib/fineract holding the MariaDB datadir, separate from the OS disk and re-provisioned with every VM
• nginx reverse proxy on :80 to the Fineract provider, plus an unauthenticated /health endpoint
• Per-VM mifos admin password generated at first boot, in a root-only file
• mariadb.service, fineract.service and nginx.service as systemd units, enabled and active
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_B4ms (4 vCPU / 16 GiB RAM) is a good starting point. The Spring Boot JVM, MariaDB and the Liquibase migrations run together and are memory hungry. NSG inbound: allow 22/tcp from your management network and 80/tcp from the API clients and operators who use the gateway. Front port 80 with TLS for public exposure, see Enabling HTTPS.

Step 1 — Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Apache Fineract by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) and HTTP (80). Review the dedicated data disk on the Disks tab, then Review + create then Create.

Step 2 — Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name fineract \
  --image <marketplace-image-urn> \
  --size Standard_B4ms \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

az vm open-port --resource-group <your-rg> --name fineract --port 80 --priority 1010

Step 3 — Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 — Confirm the services are running

systemctl is-active mariadb.service fineract.service nginx.service

All three services report active.

Step 5 — Confirm the gateway answers

curl -s -o /dev/null -w 'health -> HTTP %{http_code}\n' http://127.0.0.1/health
curl -s -o /dev/null -w 'swagger ui -> HTTP %{http_code}\n' http://127.0.0.1/fineract-provider/swagger-ui/index.html

The unauthenticated /health endpoint returns HTTP 200, and the nginx reverse proxy fronts the Fineract provider so the Swagger UI returns HTTP 200.

Step 6 — Retrieve your admin password

The administrator password is generated uniquely on the first boot of your VM and written to a root-only file:

sudo grep -E '^FINERACT_' /root/fineract-credentials.txt

FINERACT_ADMIN_USER is mifos, FINERACT_TENANT is default, and FINERACT_ADMIN_PASSWORD is the password.

Step 7 — Verify the REST API authentication

Fineract uses HTTP Basic authentication and a Fineract-Platform-TenantId header. The following reads the per-VM password and proves a wrong password is rejected with HTTP 401 while the real one returns the office list as JSON. The password value is sensitive, so it is read into a shell variable rather than printed:

sudo grep '^FINERACT_ADMIN_PASSWORD=' /root/fineract-credentials.txt | cut -d= -f2- > /tmp/pw
echo "wrong password -> HTTP $(curl -s -k -o /dev/null -w '%{http_code}' -u mifos:wrong -H 'Fineract-Platform-TenantId: default' https://127.0.0.1:8443/fineract-provider/api/v1/offices)"

The wrong password returns HTTP 401. To make an authenticated call with the real per-VM password, pass it from the root only credentials file. For example, to list the offices in the default tenant:

sudo curl -k -u mifos:<password> -H 'Fineract-Platform-TenantId: default' https://127.0.0.1:8443/fineract-provider/api/v1/offices

The response is a JSON array describing the Head Office and any branches you have created.

Step 8 — Explore the Swagger UI

Open http://<vm-public-ip>/fineract-provider/swagger-ui/index.html in a browser. The Swagger UI is the interactive API console for every Fineract endpoint, grouped by resource.

Use the Authorize button to supply your mifos credentials and the default tenant id, then expand any resource to try requests directly from the browser.

Step 9 — Browse clients and data

Expand the clients resource group to list and create clients, or the datatables group to inspect the configurable data tables that extend the core banking entities.

The users resource manages application users and their roles and permissions.

Confirm the Fineract version

ls /opt/fineract/fineract-provider.jar && echo "Apache Fineract 1.10.1 deployed"

Enabling HTTPS

The Fineract provider already serves HTTPS internally on :8443 with a self-signed certificate, and nginx fronts it on :80. For production, terminate TLS at nginx with a real domain pointed at the VM's public IP. Install certbot and request a certificate (replace the domain):

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.example.com

Backup and maintenance

All Fineract data, the tenant registry and every tenant's banking records, lives in MariaDB on the dedicated data disk at /var/lib/fineract. Snapshot that disk in Azure to back up your data, and keep the OS patched with sudo apt update && sudo apt upgrade. The platform restarts cleanly with sudo systemctl restart mariadb fineract nginx.

Support

This image is backed by 24/7 cloudimg support. Contact us by email and chat for help with tenant setup, client and loan configuration, scaling, TLS and backups.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.