Apache Fineract

Prerequisites

You need 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, because the Spring Boot JVM, MariaDB and the Liquibase migrations run together and use a lot of memory.

In the NSG, allow inbound 22/tcp from your management network and 80/tcp from the API clients and operators who use the gateway. For public exposure, front port 80 with TLS (see Enabling HTTPS).

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, select Create a resource, and search the Marketplace for Apache Fineract by SecureAnyCloud. Select Create.

On the Basics tab, 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 select Review + create and Create.

Step 2 - Deploy from the Azure CLI

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:apache-fineract-ubuntu-24-04:default:latest
az vm create \
  --resource-group <your-rg> \
  --name fineract \
  --image sac1647283583153:apache-fineract-ubuntu-24-04:default:latest \
  --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

First boot takes a few minutes. On first boot, the VM finishes its per-VM setup in the background by generating its own credentials and starting the services. If you connect as soon as the VM shows as running, wait for that setup to finish before you continue. Run sudo cloud-init status --wait on the VM.

The command prints status: done when the VM is ready. The credentials and services described below are present only after that.

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 command reads the per-VM password and shows that a wrong password is rejected with HTTP 401, while the real one returns the office list as JSON. The password is sensitive, so the command reads it into a shell variable instead of printing it:

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, take 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.

Select Authorize and enter 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 that points at the VM's public IP. Install certbot and request a certificate, replacing the example domain with yours:

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, including 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. Keep the OS patched with sudo apt update && sudo apt upgrade. To restart the platform, run sudo systemctl restart mariadb fineract nginx.

Support

This image is backed by 24/7 SecureAnyCloud 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.

Deploy on Azure

Launch Apache Fineract on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Connecting to your instance

Connect over SSH on port 22 using the private key for the key pair you selected at launch. The login user depends on the operating system variant you launched:

• Ubuntu 24.04: log in as ubuntu

ssh -i your-key.pem ubuntu@<public-ip>

The security group for this instance should allow only SSH (port 22) and HTTPS (port 443), and you should restrict both to your own address range. The Fineract provider listens on 127.0.0.1:8443 and MariaDB on 127.0.0.1:3306. Neither is exposed to the network directly, and nginx on port 443 is the only application entry point.

Confirming the platform is running

Fineract, MariaDB and nginx start automatically. Check that all three services are active:

systemctl is-active mariadb fineract nginx

active active active

The Fineract provider exposes a health endpoint. Query it over the loopback TLS listener:

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

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

Retrieving your administrator credentials

Apache Fineract ships a well-known default super-user (mifos / password). On this image, that credential is rotated to a unique per-instance password on first boot, so the default no longer works. Retrieve the generated password from the file, which only root can read:

sudo cat /root/fineract-credentials.txt

FINERACT_URL=https://<public-ip>/ FINERACT_SWAGGER_UI=https://<public-ip>/fineract-provider/swagger-ui/index.html FINERACT_ADMIN_USER=mifos FINERACT_TENANT=default FINERACT_ADMIN_PASSWORD=<generated per instance>

The tenant identifier for the default tenant is default; every API request must carry it in the Fineract-Platform-TenantId header.

Exploring the API with the Swagger UI

Browse to https://<public-ip>/fineract-provider/swagger-ui/index.html in a web browser. The instance ships a per-instance self-signed certificate, so your browser warns on the first visit. Accept the warning, or install your own certificate (see below). The Swagger UI lists every endpoint in the Fineract REST API.

The API is grouped by domain: clients, loans, savings, accounting, and the organization endpoints for offices, staff and roles.

Select Authorize to see the authentication model: HTTP Basic authentication for the user, plus the fineract-platform-tenantid header for the tenant.

Authenticating to the REST API

Every request uses HTTP Basic authentication with the mifos user and your per-instance password, and the Fineract-Platform-TenantId: default header. List the offices in the default tenant (a fresh install has one, the Head Office):

PW=$(sudo grep '^FINERACT_ADMIN_PASSWORD=' /root/fineract-credentials.txt | cut -d= -f2-)
curl -sk -u "mifos:$PW" -H 'Fineract-Platform-TenantId: default' \
  https://127.0.0.1:8443/fineract-provider/api/v1/offices | jq -c '.[0]'

{"id":1,"name":"Head Office","nameDecorated":"Head Office","externalId":"1","openingDate":[2009,1,1],"hierarchy":"."}

An unauthenticated request, or one with the wrong password, is refused with 401 Unauthorized.

Creating your first office through the API

Create a branch office as a child of the Head Office, then read it back:

PW=$(sudo grep '^FINERACT_ADMIN_PASSWORD=' /root/fineract-credentials.txt | cut -d= -f2-)
curl -sk -u "mifos:$PW" -H 'Fineract-Platform-TenantId: default' -H 'Content-Type: application/json' \
  -X POST https://127.0.0.1:8443/fineract-provider/api/v1/offices \
  --data '{"name":"sac-branch-demo","openingDate":"2020-01-01","parentId":1,"dateFormat":"yyyy-MM-dd","locale":"en"}'

{"officeId":4,"resourceId":4}

PW=$(sudo grep '^FINERACT_ADMIN_PASSWORD=' /root/fineract-credentials.txt | cut -d= -f2-)
OID=$(curl -sk -u "mifos:$PW" -H 'Fineract-Platform-TenantId: default' \
  https://127.0.0.1:8443/fineract-provider/api/v1/offices \
  | jq -r '.[] | select(.name=="sac-branch-demo") | .id')
curl -sk -u "mifos:$PW" -H 'Fineract-Platform-TenantId: default' \
  https://127.0.0.1:8443/fineract-provider/api/v1/offices/$OID | jq -c '{id,name,openingDate}'

{"id":4,"name":"sac-branch-demo","openingDate":[2020,1,1]}

The same pattern of authenticating, posting to a resource and reading it back creates clients, loan and savings products, and everything else the platform models. The full endpoint reference is in the Swagger UI.

TLS and production hardening

The image ships a per-instance self-signed certificate on port 443. For production, replace it with a certificate for your own domain. You can terminate TLS at an AWS load balancer with an AWS Certificate Manager certificate, or install a certificate directly. To use Let's Encrypt on the instance, point a DNS record at the instance and issue a certificate for <your-domain>. Then reference it from the nginx server block at /etc/nginx/sites-available/sac-fineract.

Other recommended controls:

• Restrict the security group to your own address range for both SSH (22) and HTTPS (443).
• Enable EBS encryption for data at rest.
• Keep the MariaDB port bound to localhost (the default), and never expose 3306.

These controls support teams building regulated financial workloads, but you remain responsible for your own full compliance assessment.

Maintenance

• Fineract logs: sudo journalctl -u fineract -f
• Restart the platform: sudo systemctl restart fineract
• Database: MariaDB stores its data under /var/lib/fineract on a dedicated EBS volume you can resize independently. Back it up with your regular database tooling, or migrate to Amazon RDS for managed backups and Multi-AZ failover.
• Credentials: the per-instance administrator password is in /root/fineract-credentials.txt. Change it through the Fineract API (PUT /users/{id}) and update your records.

Support

Every subscription includes 24/7 SecureAnyCloud technical support via email (sales@secureanycloud.com) and live chat, covering deployment, upgrades, tenant configuration, TLS setup, performance tuning, and MariaDB administration. Critical issues receive a one-hour average response time.

Deploy on AWS

Launch Apache Fineract with 24/7 support from SecureAnyCloud.

View on Marketplace

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com