Apache Fineract on AWS User Guide

Overview

Apache Fineract is the open source core banking engine behind the Mifos ecosystem. It provides the domain model and REST API for running a financial institution: clients and groups, loan and savings products, accounts and transactions, accounting and the general ledger, and the organizational structures (offices, staff, roles) that sit around them. Rather than a monolithic banking application, Fineract is an API-first platform you build products on - digital banks, microfinance and lending back ends, cooperatives, and fintech applications all use it as their system of record.

The cloudimg image delivers Apache Fineract 1.10.1 as a hardened, production-oriented deployment: the Fineract provider (a Spring Boot service on OpenJDK 17) serving the REST API and the Swagger UI over TLS, backed by MariaDB on a dedicated data volume, with an nginx reverse proxy terminating a per-instance certificate on port 443. The default tenant schema is migrated and ready at first boot, so you can authenticate and start creating banking entities immediately rather than running an installer. Backed by 24/7 cloudimg support.

What is included:

• Apache Fineract 1.10.1 (SPDX: Apache-2.0) at /opt/fineract, from the official archive.apache.org binary distribution; the shipped LICENSE is fingerprinted as Apache-2.0 at build time and baked into the image
• OpenJDK 17 runtime and the MariaDB Connector/J JDBC driver (LGPL-2.1, redistributable) - no proprietary database driver ships
• MariaDB serving the fineract_tenants and fineract_default schemas, bound to localhost, with the datadir on a dedicated, independently resizable EBS volume mounted at /var/lib/fineract
• nginx terminating a per-instance TLS certificate on port 443 in front of the Fineract provider, plus an unauthenticated /health endpoint for load balancers
• A per-instance administrator password (the well-known mifos / password default is rotated on first boot) and per-instance TLS material (Fineract's bundled default keystore is never used on a running instance), written to a root-only credentials file
• 24/7 cloudimg support

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:

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; 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 - the default no longer works. Retrieve the generated password (the file is readable only by root):

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. Because the instance ships a per-instance self-signed certificate, your browser will warn on first visit; accept it (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.

Click 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":"cloudimg-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=="cloudimg-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":"cloudimg-branch-demo","openingDate":[2020,1,1]}

From here the same pattern - authenticate, POST to a resource, read 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 - either 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/cloudimg-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) - never expose 3306.

These 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 cloudimg technical support via email (support@cloudimg.co.uk) and live chat, covering deployment, upgrades, tenant configuration, TLS setup, performance tuning, and MariaDB administration. Critical issues receive a one-hour average response time.