What it actually takes to run Apache Fineract in production

Apache Fineract is a capable core banking platform, and it is free. What it is not is a finished product you deploy and forget. The project says as much: there is no official production deployment guide, and the bits that keep a real system alive are left to you.

We run managed Fineract for a living, so this is the guide we wish existed when teams ask us "what does production actually look like?" No vendor gloss. Here is where it is simple, where it bites, and what the project quietly leaves on your plate.

Start simpler than you think

The first instinct with a banking core is to over-build. Resist it.

For a real but modest institution, you do not need a complicated topology. The entire thing runs in a single container without issues. As a rough marker, one container is comfortable up to around 1,000 clients and 5,000 accounts with low API traffic, on the order of three to five requests a minute. Plenty of live deployments never need more than that.

So if you are small, deploy one container, get your backups and TLS right (more on that below), and move on. The scaling problems below are real, but they are problems you grow into, not ones you provision for on day one.

The database bites first

When something does go wrong at scale, it is almost always the database. Fineract is heavy on the database. Right-size it from the start, because under-provisioning here is the most common way a Fineract instance falls over.

The failure mode worth burning into memory is connection exhaustion. Here is what it looks like in practice: Fineract uses up every available database connection, and then everything past the requests already in flight simply stops. Tenants stop working. The API stops responding. Batch jobs stop running. It is not a slowdown you notice and fix calmly. It is a full outage.

The painful part is that it is avoidable, but only if you plan for it instead of waiting for Fineract to hit the wall. Two things matter:

Tune the per-tenant connection pool settings. Fineract opens pools per tenant, so with many tenants the default settings will happily try to open far more connections than your database allows.
Put a real connection pooler in front of the database. PgBouncer, RDS Proxy, or equivalent. This is the single highest-leverage thing you can do to keep a multi-tenant Fineract stable.

Without a pooler, each tenant's connection pool piles onto the database until it hits its max connections and the instance fails. With a connection pooler in front, the connections are multiplexed and the database stays within its limit. — Without a pooler, per-tenant pools exhaust the database. A pooler keeps connections within the limit.

If you take one thing from this post, take this one. Connection exhaustion is the outage we see teams walk into most often, and it is entirely preventable.

How the topology scales

Fineract is really four roles wearing one costume. By default a single container is the write node, the batch manager, the batch worker, and the read node all at once. That is fine until it isn't, and the way you grow is by pulling those roles apart.

The progression looks like this (blue = request handling, green = batch processing, gray = infrastructure):

One container for everything (the starting point above).
Separate the read and write paths once API traffic grows.
Separate the batch manager and batch workers once your jobs get heavy.
For very heavy batch work, split the manager and workers across machines and put a message broker (RabbitMQ, ActiveMQ, or Kafka) between them so they can coordinate.

Stage 1: a single all-in-one container holds all four roles - write, read, batch manager, and batch worker - and connects down to one database. — Stage 1 - one container runs all four roles. Comfortable up to around 1,000 clients and 5,000 accounts.

Stage 2: a write and read app is split from a combined batch manager and worker, and both connect to the database. — Stage 2 - split the request path (write + read) from the batch tier as API traffic grows.

Stage 3: a write and read app, a separate batch manager, and a separate batch worker all connect to the database. — Stage 3 - separate the batch manager from the workers as jobs get heavier.

Stage 4: the batch manager hands work through a message broker to multiple workers; the write and read app and the workers both connect to the database. — Stage 4 - for very heavy Close of Business, distribute the workers behind a message broker.

That last step is what you reach for when, say, Close of Business has to chew through ten million loan accounts a night. The mechanics of that, partitioned versus non-partitioned jobs and how the manager hands work to the workers, deserve their own post, and they will get one. For now the thing to know is that the path exists and it is well-trodden.

The autoscaling trap

Here is the constraint that surprises people, because it runs against every cloud-native instinct: you cannot just turn on horizontal autoscaling and walk away.

With the default setup, all four roles live in one container, and one of those roles, the batch manager, must be a single instance per database. Run two batch managers against the same database and they start competing over job scheduling, which means jobs run twice or step on each other. So if you naively autoscale the default container from two replicas to ten, you have just created ten batch managers fighting over the same jobs.

The way out is to stop scaling the whole thing as one unit and split by role instead. A topology that works well:

Write and read together, and scale these horizontally. This is where your API load lives, and these roles scale cleanly.
Batch manager and worker together, and do not scale these. One is correct.

Naive autoscaling of the all-in-one container creates several batch managers all scheduling against one database and colliding. Splitting by role keeps an autoscaled write and read tier alongside a single batch manager and worker. — Autoscaling the all-in-one container creates competing batch managers. Split by role instead.

Get that separation right and you can scale the part that needs scaling (request handling) without ever tripping the batch manager constraint.

Multi-tenancy, and the piece Fineract is missing

Fineract supports multi-tenancy, and it does it well at the data layer: each tenant can live in its own database, configured through Fineract's tenant settings. Once you are running a lot of tenants, splitting them across multiple databases is a sensible move for both isolation and connection budget.

What Fineract does not give you is a way to manage those tenants. There is no built-in tooling to create, configure, or decommission a tenant cleanly. Out of the box you are editing tenant store rows by hand and restarting servers, which is slow and easy to get wrong at scale.

This gap is exactly why we built the Finecko Hub. It wraps the whole tenant lifecycle behind a web UI and a REST API, so creating or removing a tenant is a form or a single call rather than manual SQL and a restart, and it does it with zero downtime. If you are self-hosting and you have more than a handful of tenants, you will end up building some version of this yourself. It is one of the larger pieces of "the project leaves it to you."

The unglamorous essentials

None of the following is interesting, and all of it is what separates a production system from a demo.

Backups and secrets. Your operating team owns these. Banking data with no tested restore path is not a production system, and credentials living in plain config are an incident waiting to happen. This is table stakes, but it is on you, not on Fineract.

TLS. Fineract ships with a built-in self-signed certificate. Remove it and terminate real TLS, whether at the application or at a proxy in front of it. The self-signed default is for getting started, not for production.

Migrations are not as automatic as they look. Fineract runs its Liquibase database migrations on application startup, which is convenient right up until you scale. Once multiple instances start at once, several of them try to run the migrations at the same time, and the Liquibase changelog lock gets stuck. There is no automatic recovery from that; you resolve it by hand. The fix is to stop relying on migrate-on-startup and instead run migrations as a separate, single step before you deploy the application. If you are heading for more than one instance, set this up early.

So, is it worth running yourself?

Honestly, sometimes yes. If you are small, one well-configured container with proper backups and TLS will serve you for a long time, and Fineract gives you a serious banking core for the cost of the infrastructure.

But be clear-eyed about what production means past that point. It means owning connection pooling, a topology that respects the batch-manager constraint, a real migration step, tenant management tooling Fineract does not provide, and the on-call reality when connection exhaustion takes the whole thing down at 2am. That is a genuine operations job, and it is the part the free license does not cover.

A production-ready topology: clients reach a TLS reverse proxy, an autoscaled write and read app tier and a single batch manager and worker tier both go through a connection pooler to the database and a read replica, and the Finecko Hub manages tenant lifecycle. — A production-ready Fineract topology: an autoscaled app tier, a single batch tier, a connection pooler, and the Finecko Hub for tenant management.

That is the part we take off your plate. Finecko runs managed Apache Fineract, with the Hub, the right topology, and the boring-but-critical pieces handled, so you get the open-source core without the operations. If you would rather run it yourself, take everything above and you will avoid the traps we see most often. Either way, now you know what production actually asks for.