Running Apache Fineract on AWS: what the platform needs from your account
Fineract is a headless core banking application: it exposes REST APIs and ships no user interface of its own, so the front end, identity provider and integrations are separate components you place in your AWS accounts. PostgreSQL is the recommended database, and the project deprecates MariaDB and MySQL under FSIP-9, so the database layout is the first AWS design decision your team owns. Choosing between Amazon RDS and Aurora PostgreSQL, the account structure, network placement and how instances are split across read, write and batch roles are yours to make and document.
The Apache Fineract documentation describes the instance types (read, write and batch) set through environment variables, the recommendation of one write instance, one batch instance and multiple read instances on read replicas, and the rule that Liquibase migrations run only on write instances. The README warns that a production deployment can be complex, costly and time-consuming, and the project does not provide a comprehensive production deployment guide. The AWS-specific choices, such as where the S3 document store lives, how workloads authenticate, and how events and monitoring are wired, are therefore not covered by the project and need an explicit design. Ask your team to confirm which AWS services and regions are approved for core banking data before any build starts.
Treat the account layout as a control, not a convenience. Confirm with your security and compliance leads how tenant databases, document buckets, event topics and metrics will be separated by environment and by tenant, who holds administrative rights, and where backups are kept. Confirm current Aurora and RDS engine versions, S3 configuration properties and Amazon MSK authentication options directly with AWS and the Apache Fineract platform documentation for the release you plan to run, because these details change between releases.
Which AWS service fits each Fineract component
This table compares the AWS option for each Fineract component: the database, document storage, events and COB partitioning, and metrics. Read each row for when the option fits, what to confirm with AWS or the Fineract project before committing, and what it adds to day-to-day operations. The main takeaway is that PostgreSQL is the only database Fineract recommends, so the managed choice is about operations, not compatibility.
| Component | When the option fits | What to confirm | What it adds to operations |
|---|---|---|---|
| Database: Amazon RDS for PostgreSQL | A single-region deployment where a standard managed PostgreSQL instance meets your recovery and sizing targets | Supported PostgreSQL major version against the Fineract release you run, and the tenants database layout with every tenant schema | Managed backups, minor version patching windows, and parameter groups that must match the UTC and pool settings Fineract expects |
| Database: Aurora PostgreSQL | Read-heavy load where you plan read instances on replicas and need fast failover within the cluster | Compatibility of your Liquibase migration path and read replica routing with Fineract's read, write and batch instance types | Cluster endpoints for writer and readers, cluster-level cost and storage model, and different upgrade behavior from RDS |
| Document storage: Amazon S3 with instance profile credentials | Client and KYC documents that must sit in AWS, with the application running on EC2 or EKS with an attached IAM role | Which FINERACT_AWS_* properties your release reads, and that instance profile credentials are supported in your exact version | IAM policy scoped to the bucket, bucket encryption and retention settings, and access logging for document reads |
| Events and COB partitioning: Amazon MSK with IAM authentication | Kafka-based external events or remote COB partitioning where you want AWS to run the brokers | Whether your Fineract build supports Kafka with IAM SASL settings, and the topic and partition layout for COB workers | Broker sizing, version upgrades, client IAM policies, and monitoring of consumer lag |
| Events and COB partitioning: self-managed Kafka or ActiveMQ | Teams that already run a broker platform or need a JMS broker, since events are disabled by default | Which broker Fineract's event and remote partitioning options support in your release and the configuration keys for each | Broker patching, storage, failover and backup are your responsibility, on EC2 or Kubernetes |
| Compute and metrics: Amazon CloudWatch | Central dashboards and alarms for host, load balancer, RDS or Aurora, and MSK metrics in one account | Which Fineract metrics are exposed through the actuator and how they can be exported to CloudWatch in your build | Log and metric ingestion cost that grows with volume, alarm tuning, and retention settings you must set |
How Fineract credentials should work on AWS
Fineract stores client and KYC documents in an S3-compatible document store, configured through FINERACT_AWS_* properties for endpoint, region and credentials. On AWS, the cleanest pattern is to attach an IAM role to the compute that runs Fineract and let the application use instance profile credentials, so that no long-lived access key sits in configuration. Confirm the exact property names and behavior for your release in the Fineract platform documentation.
- Owner: The platform team owns the IAM role attached to the compute, and the security team reviews its policy.
- Scope: Grant access only to the document bucket or prefix and only to the actions the document feature needs. Confirm those actions in a test environment.
- Rotation: Instance profile credentials are temporary and refresh through the instance metadata service. Confirm this behavior for your container runtime or Kubernetes node setup.
- Verify: Upload, retrieve and delete a test document under the Fineract role, then confirm that a role without access is refused.
Check that no static access key appears in environment files, container images, Helm values or the tenant configuration.
Fineract reads tenant connection details from a tenants database, and each tenant has its own PostgreSQL schema. The database credentials are the most sensitive secrets in the deployment, because they grant access to every client's ledger. Keep them in a secrets service and inject them at runtime, so they stay out of images, compose files and version-controlled manifests. PostgreSQL is the recommended database for Fineract.
- Owner: The database team owns the PostgreSQL roles and the Fineract team owns the application roles that connect to each tenant schema.
- Role separation: Where your design separates read, write and batch instances, give each instance type only the grants it needs. Liquibase migrations run only on write instances, so limit the migration role to that path.
- Rotation: Plan rotation for RDS or Aurora credentials with a window in which connection pools reconnect. Confirm how your secrets service signals updated values to running pods or tasks.
- Network path: Restrict access to the database endpoint to the Fineract subnets and security groups, and confirm that no other workload can reach it.
Check that the tenants database credentials, each tenant schema grant and the migration role are documented, with a named owner for each.
The Fineract README shows a default development login, mifos with a published password. Anyone who has read the project documentation knows it, so it must be removed or replaced before any environment holds real client data. The same rule applies to copies of production data restored into test or training environments, because the default login would expose those records too. Fineract supports OAuth2 and HTTP basic authentication, so confirm which model each environment uses.
- Owner: The application owner or security lead decides the authentication model for each environment and signs off on the change.
- Replace before go-live: Change or remove the default account in every tenant, including non-production environments and restored copies.
- Store the new secret: Hold replacement credentials in a secrets service with named owners and an audit trail, and keep no copies in shared documents or chat.
- Rotation: Set a rotation schedule for administrative accounts and a documented procedure for emergency revocation.
- Verify: Confirm that the default login is rejected on each tenant, through the load balancer and on any direct instance port that is reachable.
Check that the default login fails in every environment before any data migration or user onboarding begins.
Fineract can publish external business events, such as ClientCreated, to Apache Kafka or to a JMS broker, and this is disabled by default. Its Close of Business job can also coordinate remote partition workers through ActiveMQ or Kafka. If the team chooses Amazon MSK, it must confirm whether IAM authentication can be configured for both the event traffic and the COB partitioning traffic in the release it runs. That answer depends on the client libraries and security settings the project supports, so verify it with a working test rather than assuming it.
- Owner: The streaming team owns the MSK clusters, IAM policies and topic access controls, and the Fineract team owns the event publishing configuration.
- Confirm support: Check the Fineract documentation for the release in use for the supported Kafka security settings, including SASL and IAM options, before designing around them.
- Enable deliberately: Turn on event publishing per environment only after topics and consumers exist and their access is reviewed.
- COB traffic: Test remote partitioning on MSK end to end, including worker authentication, before relying on it for a production COB window.
- Fallback: Decide what happens to events and COB workers when the broker is unreachable, and document the recovery steps.
Check that the IAM path works for every Fineract component that connects to the broker, including the publisher, the consumers and the batch workers.
How instance types and COB shape the AWS layout
Instance roles decide how many compute units the AWS layout needs and where each one sits. The Fineract documentation describes read, write and batch instances selected through environment variables, and recommends one write instance, one batch instance and multiple read instances on database read replicas for high load. Plan the AWS layout as three distinct workloads rather than one scaled-out service. Each workload has its own container count, its own health checks and its own database endpoint, so the read instances should point at a reader endpoint (an RDS or Aurora reader) while the write and batch instances point at the writer. Ask your team to confirm the exact environment variables for each role against the version you deploy, since these settings change between releases.
Liquibase database migrations run only on write instances, according to the documentation, and on Kubernetes they can run as a separate job using the liquibase-only Spring profile. On AWS, this means the migration step belongs in your deployment pipeline, not in the autoscaling group or ECS service that serves reads. Scale the read tier freely, but do not let new read tasks start against a schema that a write instance has not yet migrated. Treat the migration as a gated, one-time step per release, and confirm how your chosen compute service (ECS, EKS or EC2) orders it ahead of other tasks.
The README notes that the Close of Business (COB) Spring Batch job can run for several hours on deployments with millions of accounts. It supports remote partitioning across worker nodes coordinated through ActiveMQ or Kafka. If you plan to use Amazon MSK for partitioning, measure the COB duration on a production-sized data set before you fix the batch window, the number of worker nodes and the broker sizing. Also measure read latency on the replicas during COB, connection counts against the RDS or Aurora instance class, and the time between COB completion and the start of business. Events such as ClientCreated are disabled by default, so decide deliberately whether to enable them, because enabling them adds broker traffic that your MSK cluster must absorb during the same window.
Setup sequence for Fineract on AWS
This sequence takes an empty AWS account to a Fineract deployment where tenant connections, document storage, scheduled batch work and monitoring are each confirmed before the next layer is added. Each step ends with a check the team can run, so faults are found while the system is still small.
Define the VPC and private subnets
The cloud or network team creates a VPC with private subnets for the Fineract instances and the database, and keeps database and application subnets free of direct internet routes. Inbound access is limited to the load balancer or reverse proxy that your security team approves. Confirm the route tables and security groups with a reachability test from a bastion or VPN host: the application subnet should reach the database port and nothing else should. Record the subnet CIDRs and security group IDs, because every later step depends on them.
Provision PostgreSQL and the tenants database
Create the PostgreSQL instance as Amazon RDS or Aurora PostgreSQL in the private subnets, with encryption, automated backups and a parameter group your DBA reviews. Fineract's documentation treats PostgreSQL as the recommended database, so confirm the engine version against the Fineract release you plan to run. Create the tenants database and at least one tenant schema, then confirm from an application subnet host that a connection succeeds with the intended credentials. Also confirm that the database runs in UTC, as the Fineract PostgreSQL guidance requires for the platform.
Create the S3 bucket and instance role
Create a private S3 bucket for client and loan documents, with public access blocked, default encryption enabled and versioning reviewed against your retention policy. Create an IAM role that grants only the object actions Fineract needs on that bucket, and attach it to the instances as an instance profile. Configure the FINERACT_AWS_* properties for region and endpoint, and leave static access keys out of the configuration. Verification: upload a test document through the Fineract document API, then confirm the object exists in the bucket and that the upload used the instance role rather than a stored key.
Deploy the write, batch and read instances
Deploy one write instance, one batch instance and the read instances that your load profile requires, each set through its instance type environment variable. Point the write and batch instances at the primary database and the read instances at read replicas, if you have created them. Place the instances behind the load balancer only after their health endpoints respond. Verification: call a read endpoint and a write endpoint with a tenant header, confirm each request reaches the intended tenant schema, and check the logs of each instance for connection errors. Do not expose the batch instance to general API traffic.
Run Liquibase on the write path
Run the schema migrations only through the write instance, because the documentation states that Liquibase migrations run on write instances alone. On a container platform, you can run the liquibase-only Spring profile as a separate one-time task before the other instances start. Keep a snapshot of the database before the first run and record the Liquibase changelog state afterward. Verification: confirm the migration task exits successfully, the changelog table shows all expected entries, and the read and batch instances start cleanly against the migrated schema.
Confirm the broker design before enabling events and COB partitioning
Event publishing to ActiveMQ, another JMS broker or Apache Kafka is disabled by default, and COB remote partitioning depends on ActiveMQ or Kafka for coordination. Before enabling either feature, the architecture team should document the broker choice, network path, authentication and topic or queue ownership, and confirm each with the broker team. Enable events in a non-production tenant first, then confirm a ClientCreated event reaches the consumer. Do not enable COB partitioning until the worker nodes and broker are proven in the same environment.
Test a COB run on non-production data
Load a representative, non-production dataset into a test tenant with loan accounts across the range of products you will run. Trigger Close of Business through the scheduler or API on the batch instance, and record start time, end time and any failed business steps. Compare the total duration against your operating window, then repeat the run after adjusting the connection pool or partitioning settings if needed. Verification: the run completes without locked loans or errors in the job history, and the results match the expected balances on sampled accounts.
Configure CloudWatch metrics and alarms
Send container or host metrics, RDS or Aurora metrics and application logs to CloudWatch, then define alarms for database connections, storage, instance health, failed batch jobs and S3 access errors. Route alarms to the operations on-call channel and confirm each alarm fires by triggering a controlled test condition where safe. Document the metric names, thresholds and owners in the runbook. Verification: each alarm reaches the notification target during the test, and a dashboard shows the write, batch and read instances side by side.
Security controls to design into the AWS account
Fineract holds client identities, loan balances and ledger data, so the AWS account around it needs controls the team can verify itself. The cards below cover transport, network placement, identity, secrets, encryption and logging, and each one maps to a setting or boundary that your own team configures and checks.
HTTPS only at the application
Fineract's documentation strongly encourages HTTPS only and exposes SSL settings through environment variables such as FINERACT_SERVER_SSL_ENABLED. Decide whether TLS terminates at an AWS load balancer or inside the container, then set the variables to match that choice. Check that plain HTTP listeners are closed on the load balancer and that no path reaches the application unencrypted.
Private database and broker endpoints
Place the RDS or Aurora PostgreSQL cluster and the MSK brokers in private subnets with no public accessibility, and restrict their security groups to the Fineract instance groups. Confirm that the read, write and batch instances can reach the database and brokers, and that nothing else in the VPC or peered networks can. Review the route tables and security groups after every change.
Least-privilege instance roles for S3
Fineract's S3 document store can use instance profile credentials through the FINERACT_AWS_* properties, so no long-lived access keys need to be stored. Attach a role that allows only the actions and bucket prefixes that document storage requires, and deny access to other buckets. Ask your team to confirm that the role is scoped per environment and that keys are not present in images or configuration files.
Replacing the default development login
The Fineract README shows a default development login of mifos with a known password, which must be changed for any real deployment. Remove or rotate that account before the first environment is reachable, and store the replacement credentials in AWS Secrets Manager or Systems Manager Parameter Store rather than in task definitions. Confirm that OAuth2 or basic authentication is configured on every path that is exposed.
Encryption and key ownership at rest
Decide which customer-managed AWS KMS keys protect the database, the S3 document bucket, the MSK cluster and the backup copies, and who holds administrative rights over those keys. Separate key administration from data access so that the people who run Fineract cannot silently disable encryption. Record the key policy, rotation settings and deletion protection as part of the design, and confirm them with your security team.
Audit logging of administrative and batch activity
Enable AWS CloudTrail for management events across the account and send Fineract application logs and COB job output to CloudWatch Logs with retention set by your policy. Administrative actions in Fineract and the scheduled Close of Business runs should be traceable to a named user or job. Confirm that log groups are write-protected from the application roles and that alerts exist for failed batch runs.
What CloudWatch can and cannot tell you about COB
CloudWatch shows you the infrastructure around Fineract's Close of Business run, but it does not show you what the batch did to each loan. Use it for CPU, memory, database connections, read and write latency and free storage on the RDS or Aurora cluster, along with container or node health on the hosts that run the batch instance. Fineract's own job run history in the API and its application logs remain the record of which Loan COB business steps completed, which failed and which accounts were left locked. Before the first production cycle, confirm which metrics your Fineract release publishes to CloudWatch, if any, because the exact set depends on the release and its configuration, and do not assume a metric exists until you have seen it in the account.
Some signals will need application-level instrumentation or log-based metrics that your team builds and owns. Batch duration per run, the number of loans processed per business step, the count of loans in a locked or error state after COB, and the time between the scheduled start and the first business step are the figures that tell you whether the close is drifting toward the next business day. Plan a CloudWatch log metric filter or a custom metric for each one, and confirm the log format of your release before writing the filter. Ask your partner or vendor to document which log lines mark the start and end of each step so the filters are not built on guesses.
Plan the alarms and dashboards as part of the cutover, not after it. Create an alarm on the batch not finishing within the window agreed with your operations team, an alarm on any loan left in a lock state, an alarm on database connection saturation during the batch, and an alarm on replica lag for read instances. The dashboard should place the COB start time, the batch duration, database load and the lock count on one timeline so an on-call engineer can see cause and effect. Test each alarm by triggering it in a non-production tenant, and agree who is paged, which runbook applies and how the alarm is closed after a repair.
What to confirm before committing to this AWS design
Several parts of an AWS design for Fineract depend on the release in use, your database topology, your regions and your security policy, and none of them can be settled from documentation alone. Resolve these questions with the right owner before you approve the architecture, because each one changes components, cost or the build sequence.
MSK IAM authentication support
Confirm whether the Kafka client configuration in the Fineract release you plan to run supports IAM authentication to Amazon MSK, and which SASL mechanism and client settings it expects. Ask the platform engineering lead to test a connection to a non-production MSK cluster with the intended IAM role before committing to MSK for business events or COB partitioning. If IAM is not supported, plan for a different credential method and record the decision.
RDS or Aurora for read replicas
Decide whether Amazon RDS for PostgreSQL or Aurora PostgreSQL fits the read instance topology you expect, including the number of read replicas, failover behavior and how the tenants database is replicated. Ask the database team to confirm replica lag tolerance for read-heavy screens and reporting. Fineract's documentation recommends one write instance, one batch instance and multiple read instances on read replicas for high load.
S3 document settings across regions
Confirm how the FINERACT_AWS_* endpoint, region and credential settings behave when the S3 bucket sits in a different region from the application or when you use a cross-region replication design. Ask the cloud architect to test instance profile credentials on each node type, and to confirm bucket policy, encryption and retention rules with the data protection owner before documents are uploaded.
Cross-AZ traffic and COB runtime
Estimate the cost of cross-availability-zone traffic between Fineract instances, the database, MSK brokers and worker nodes, and model how long Close of Business runs at your expected account volume. The README notes that COB can run for several hours on deployments with millions of accounts. Ask the finance lead and the platform team to agree a cost model and a COB window before choosing instance sizes and partition counts.
Permitted AWS services
Confirm with the security and compliance owner which AWS services your internal policy allows, such as managed Kafka, managed PostgreSQL, S3 and CloudWatch, and which regions, encryption services and logging options are approved. Some services may need a formal exception or a different design. Settle this before the architecture review, since removing a service later changes the build sequence and the test plan.
Questions buyers ask about running Fineract on AWS
What drives the cost of running Fineract on AWS, and which parts are one-time?
The cost is driven by the size of the environment, the number of tenants, the database tier, the volume of document storage, the event platform, and the amount of design and testing work before go-live. Build costs are one-time: architecture, infrastructure as code, database setup, integration build, migration and testing. Recurring costs are the AWS bills for compute, RDS or Aurora, S3, MSK, CloudWatch and data transfer, plus patching, backups, monitoring and support. Ask for a written scope that separates these two groups, lists the AWS services assumed, and states which costs stay in your own accounts so you can compare them with your current hosting bill.
How long does an AWS build for Fineract take, and what sets that duration?
The duration depends on the scope agreed in writing, not on a fixed template. The main drivers are the number of environments, whether you use RDS or Aurora PostgreSQL, whether MSK with IAM authentication is part of the first release, how many integrations and tenants must be connected, the data migration volume, and how quickly your network, security and data owners can approve decisions. Ask for a timeline that shows milestones for infrastructure, application configuration, integration testing, migration rehearsals and go-live readiness, with the client dependencies marked on each one.
What does the bank's own team need to provide for an AWS deployment?
Your team needs to provide several things before work starts and throughout the build:
- AWS accounts for each environment, with the organization structure, billing and guardrails that your policies require
- Network approvals for VPC design, subnets, routing, private connectivity and any firewall or proxy rules
- Named data owners who can confirm client, loan and ledger data, approve migration mappings and sign off reconciliation results
- A test calendar that reserves business users, change windows and sign-off sessions
- Identity and access decisions, including who holds administrative roles and how production access is granted
Request a written list of these dependencies with owners and dates in the scope.
Can an internal platform team build and run Fineract on AWS without a partner?
Yes, an internal team can build and run Fineract on AWS if it has experience with AWS networking, managed PostgreSQL, Kubernetes or container platforms, Java services, and core banking operations. The Fineract README warns that a production deployment can be complex, costly and time-consuming, and that the project does not provide a comprehensive production deployment guide. Assess your team against the skills listed in the scope, check whether people with those skills are available for the full project and for ongoing operations, and decide which parts you want to keep in-house and which you want to outsource.
Does DeployOpen plan and implement Fineract on AWS inside our own accounts?
DeployOpen plans, implements, hardens, backs up and documents self-hosted open-source platforms inside the client's own infrastructure, including their cloud accounts. For an AWS deployment, that means the Fineract environment, RDS or Aurora PostgreSQL, S3 document storage, MSK integration and CloudWatch monitoring are built in your AWS accounts, under your control. Engagements are normally fixed-scope, with scope, deliverables and timelines agreed in writing before work starts. Ongoing support, upgrades and testing are available as retainers.
Which AWS security and compliance evidence does a Fineract deployment need?
Start by mapping your control requirements to the design: identity and access for administrators, encryption for the database and object storage, network isolation, secrets handling, logging and monitoring, backups and tested restores. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports, attestations or certifications. Independent auditors and certification bodies perform those assessments. Ask for a written list of the evidence that will be produced, who keeps it, and how it stays current after go-live.
Does Fineract need to run on AWS with instance profile credentials for S3?
Fineract's S3 document store is configured through FINERACT_AWS_* properties for endpoint, region and credentials, and those settings include instance profile credentials. Using instance profile credentials means the application does not hold long-lived access keys in its configuration. Confirm the exact property names and the IAM policy needed for your Fineract version in the platform documentation, then ask your build partner to show how the role is attached to the workload and how access is tested before go-live.
How DeployOpen scopes and delivers Fineract on AWS
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside the client's own AWS accounts. For Fineract on AWS, the work starts with a written scope covering the database, document storage, event streaming, metrics and the write, read and batch instance layout, and is delivered in that agreed scope.
How we scope
- Written scope names the AWS accounts, regions, VPC layout and who owns each account.
- Scope states whether PostgreSQL runs on Amazon RDS or Aurora and who manages backups.
- Scope lists which MSK topics, S3 buckets and CloudWatch dashboards are in and out of the engagement.
How we build
- Build covers instance profile access for S3 document storage using the FINERACT_AWS_* settings.
- MSK connections are configured with IAM authentication, and COB partitioning is tested against the agreed topics.
- Read, write and batch instances are deployed separately, with Liquibase migrations confirmed to run only on write instances.
How we hand over
- Handover includes configuration records, IAM policy documents and a description of every AWS resource created.
- Runbooks cover failover of the database, rotation of credentials and checks on COB job progress.
- Your team receives CloudWatch alarm definitions and a test log showing that the agreed checks passed.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer, scoped separately from the build.
- Retainer scope can cover Fineract release upgrades, which the project publishes quarterly with end-of-life archiving.
- Confirm with your auditors which controls and evidence the AWS setup must produce before go-live.
