Apache Fineract multi-tenant deployment: when one platform serves several institutions
If a group, network or brand owner wants several institutions or brands to run on one Apache Fineract platform, the platform can support that model. Fineract is multi-tenant: according to the project README, API requests carry a Fineract-Platform-TenantId header, and tenant database connections are configured from a tenants database. Tenancy does not, however, remove the need for separate planning of data handling, upgrades and capacity. Each tenant still has its own products, users and accounts, but the tenants share the same application instances, the same release cadence and the same batch windows. That shared footprint is why the model is harder than it looks. A change to the platform, such as a quarterly release or a schema migration, reaches every institution at once, so one tenant's go-live date can constrain another's upgrade. Batch processing is shared too. The Close of Business Day Spring Batch job can run for several hours on deployments with millions of accounts, and a combined book across tenants can push that window past what any single institution would have planned. The README also warns that production deployments can be complex, costly and time-consuming, and the project does not provide a comprehensive production deployment guide. The design therefore has to be written down by the implementer, not inherited from the project. Before building anything, the implementer should write a short tenancy design record. It should list each tenant, its tenant identifier, its data isolation approach, its branding and product ownership, its upgrade window and its reporting obligations. It should also state which parts are shared, such as the platform release, the batch schedule and the database cluster, and who approves changes that affect more than one tenant. Ask the project team and your own environment to confirm how tenant provisioning is performed in the release you intend to run, because the exact procedure depends on the version and deployment method. This page covers the tenancy layer only: how tenants are identified, provisioned and separated, and how per-tenant upgrades and operating limits are handled. Product design for each institution is covered in the sibling topic on implementation planning and cost. Hardening of tenant isolation, authentication and API exposure is covered in the security hardening topic. Uptime design for read, write and batch instances is covered in the high availability topic. Read those alongside this page before fixing the architecture.
Which Fineract pieces carry tenant identity and separation
Multi-tenancy in Apache Fineract depends on a small set of components that work together: a tenants database that holds connection settings, a tenant identifier sent on every API call, and instance types that split reads, writes and batch work. Each piece needs a confirmed setup in your own environment before you rely on it for separation between institutions or brands.
Tenants database and connection settings
The README states that tenant connections are configured from a tenants database, so this store decides which PostgreSQL database each tenant identifier resolves to. Changes to tenant records affect live routing, which makes access control and change management for this database a governance matter. Confirm which team owns it, how tenant records are created and reviewed, and whether a single running instance connects to one tenant database or several.
Fineract-Platform-TenantId request header
API requests identify the tenant through the Fineract-Platform-TenantId header, according to the README. Any client, gateway or integration that omits or misstates this header is a point where requests can reach the wrong tenant context. Confirm whether your API gateway or reverse proxy sets, overwrites or strips this header, and whether clients can set it freely.
Write, read and batch instance types
The Fineract documentation describes write, read and batch instance types set by environment variables. Liquibase migrations run only on write instances, and the Close of Business batch job belongs on its own instance. Confirm which instances are assigned to each role in every environment, and that no instance runs a role it was not sized for.
PostgreSQL databases behind each instance
The README recommends PostgreSQL, and the official Docker image ships only its JDBC driver, so each tenant's data sits in PostgreSQL databases. Separation between tenants depends on how those databases, schemas and credentials are laid out, which the project's documentation does not prescribe. Confirm the layout with your DBA, including whether each tenant has its own database, what credentials each connection uses, and how connection pools are sized per tenant and per instance type.
Read replicas and connection routing
The documentation recommends multiple read instances on database read replicas for high load. Reads routed to a replica must still carry the correct tenant identifier, or they can return another tenant's data if routing is misconfigured. Confirm how replicas are mapped to tenants, how replication lag is handled for reads that follow writes, and which tests prove a read for one tenant never returns another tenant's records.
Per-tenant upgrade and migration scope
Liquibase migrations run on write instances, and in a shared platform one upgrade touches every tenant that the write instance serves. Plan whether all tenants move to a new 1.x release together or in staged groups, and confirm how each tenant database is migrated and rolled back. Ask your team to define which tenants share an instance and which need their own, before the first upgrade is scheduled.
Shared platform or one deployment per institution: the trade-offs
This table compares one shared Fineract platform with several tenants, separate deployments per institution, and a hybrid model where regulated entities run their own deployment while brands share one. Read each row against your own regulatory perimeter, product catalog and operating team, since the operational cost of each option grows with the number of Fineract instances you must upgrade, monitor and back up. The main takeaway is that tenant separation in one platform lowers infrastructure duplication but concentrates upgrade timing, batch windows and incident impact, while separate deployments trade that concentration for repeated operating effort.
| Decision area | One shared platform, several tenants | Separate deployment per institution | Hybrid: regulated entities separate, brands shared |
|---|---|---|---|
| When it fits | Brands or entities share a product catalog, chart of accounts and regulatory perimeter under one governance model | Each institution has its own licence, regulator, data residency rule or sale or wind-down path | Regulated entities need isolated ledgers or perimeters, while marketing brands under one entity share products |
| Upgrades to Fineract releases | All tenants move together on one release and one Liquibase run on the write instance, so regression testing covers every tenant | Each deployment is upgraded on its own schedule, which allows staggered change but multiplies test and release effort | Upgrades are grouped per perimeter: one shared release for brands, separate schedules for each regulated entity |
| Close of Business batch window | One batch job serves all tenants, so a long run for a large tenant can delay others; confirm how partitioning is sized per tenant | Each deployment runs its own batch window sized to its own account volume, which isolates delays | Shared batch for low-risk brands, dedicated batch for large or regulated entities; confirm capacity planning per group |
| Incident blast radius | A fault in the shared write instance, database or configuration can affect every tenant at once | A fault stays within one institution, but outages and fixes must be handled per deployment | Limited to the affected perimeter, though shared components inside a group still carry a common failure path |
| Access administration | One identity setup and tenant-level roles; a misconfigured role can expose another tenant's data, so access reviews must check tenant scope | Separate user stores or realms per deployment simplify separation but duplicate staff onboarding and offboarding | Two administration models to maintain; reviews must cover both shared and dedicated tenant scopes |
| Shared write and batch instances | Tenants usually share one write instance and one batch instance, with the tenant identifier on each API call routing requests | Each deployment has its own write, batch and read instances, so no instance is shared across institutions | Regulated entities get dedicated write and batch instances; brands may share them, which the design must confirm |
| Database and tenants database | Tenants share a PostgreSQL server, with connections configured from the tenants database; confirm schema and backup separation per tenant | Each institution has its own database server or cluster, backups and restore points | Dedicated databases for regulated entities, shared database for brands; confirm restore procedures per tenant |
| Infrastructure and operating cost | Lower infrastructure and fewer instances, but one team must support the shared platform for all tenants | Higher infrastructure and staffing per institution, with cost scaling with the number of deployments | Cost sits between the two models; ask for a per-deployment and per-tenant breakdown in any quote |
| Questions to confirm before choosing | Whether regulators accept shared infrastructure, whether tenants can be moved or separated later, and whether one release suits all products | Whether the number of deployments is manageable for your team and how shared components like monitoring are handled | Which entities form the regulated perimeter, and whether the design allows moving a brand between groups later |
Building a multi-tenant Fineract deployment step by step
This sequence takes a Fineract platform from an agreed tenant model to a working multi-tenant deployment in which each institution or brand is onboarded, verified and isolated before it holds real data. Each step ends with a check you can run and record before moving on.
Fix the tenant model and naming standard
Before any infrastructure is built, the bank or platform owner decides how many tenants will exist, which institution or brand each one serves, and how tenant identifiers are named and kept stable. Agree who approves new tenants, how a tenant is retired, and whether each tenant has its own database schema or shares one. Record the decisions in a short design note that engineering, security and operations all sign. The step is done when every planned tenant has an approved identifier and owner, and the naming rule can be applied to a tenant that does not exist yet without argument.
Provision PostgreSQL as the database platform
Provision PostgreSQL as the database for the deployment. The Fineract README names PostgreSQL as the recommended database and states that MariaDB and MySQL are deprecated under FSIP-9, so new multi-tenant work should not start on those engines. Your platform or database team sets up the instances, backups, network access and monitoring in your own environment, and confirms the version against the Fineract documentation for the release you intend to run. The check is a successful login from a test host into an empty server with backups configured and restore tested once.
Create the tenants database and register connections
Create the tenants database that Fineract reads to find each tenant's data store, then register one connection entry per tenant with its host, database name and credentials held in your secrets store. Use the identifiers fixed in the first step so that the header value a client sends maps to exactly one connection. Keep application credentials per tenant and limit each account to its own database. The check is a query against the tenants database that lists every planned tenant with the expected connection settings, and a test connection from the application host to each tenant database succeeding.
Set write, read and batch instance types
Configure each Fineract instance with its role through environment variables: write, read or batch. The documentation describes these instance types and recommends one write instance, one batch instance and multiple read instances on database read replicas for high load. Confirm with the vendor or the documentation for your release which settings apply to your version and how the batch instance is isolated from interactive traffic. The check is that each instance reports its configured type at startup and that a write request is accepted only by the write instance.
Run Liquibase migrations on the write instance
Schema changes are applied by Liquibase, which the documentation says runs only on write instances. On a plain host deployment, start the write instance once against each tenant database so migrations complete before other instances serve traffic. On Kubernetes, run the migration separately with the liquibase-only Spring profile, then start the other workloads. Capture the migration log for each tenant. The check is that every tenant database reports the expected change set history with no failed or pending entries, and that read and batch instances start cleanly against the migrated schema.
Onboard a first tenant and verify header routing
Create the first tenant through the API and then send a request with its Fineract-Platform-TenantId header to confirm that it reads and writes the correct database. Repeat the call with the header omitted, with an unknown identifier and with another tenant's identifier, and confirm each is rejected or returns no data from the wrong tenant. Record the responses. The check is that the first tenant's records appear only in its own database and that the negative tests fail closed, which shows that routing and data separation work before a second tenant is added.
Add tenants one at a time with a rehearsal
Add each further tenant in its own change, following the same steps as the first: register the connection, run migrations if needed, create the tenant, and repeat the header tests. Before the tenant goes live, rehearse the full onboarding on a non-production copy and time the steps your team actually performs so the production change is predictable. Your operations team owns the change record and rollback plan for each addition. The check is a signed rehearsal record and the same routing tests passing in production for that tenant, with existing tenants unaffected.
Replace the default login before real data
The README shows a default development login, mifos with a shared password, which must be changed for any real deployment. Before any tenant holds real client or account data, replace default credentials for the platform and for each tenant administrator, remove or disable unused accounts, and serve the API over HTTPS only using the SSL settings the documentation describes, such as FINERACT_SERVER_SSL_ENABLED. Confirm the vendor or documentation settings for your release. The check is that the default login is rejected on every tenant, that plain HTTP requests are refused, and that the security team has reviewed the results.
Isolating tenant data, credentials and API access
In a multi-tenant Fineract platform, one database, one application and one API serve several institutions or brands, so a single misconfiguration can expose another tenant's data. The controls below keep each tenant's database access, tenant identifiers, transport security and API clients separate and verifiable.
Separate database credentials per tenant
Each tenant's connection in the tenants database should use its own database user and password, not a shared application account. Separate credentials make it possible to rotate or revoke one tenant's access without touching the others, and they make database audit logs attributable to a single tenant. Confirm how credentials are stored for each tenant entry and who can read them.
Least-privilege database roles
Each tenant database role should hold only the privileges the Fineract application needs for that tenant's schema, with no rights over other tenant schemas, server administration or other databases. Review whether migration rights are granted only to the role used on write instances that run Liquibase migrations. Ask your DBA to test that a tenant role cannot read another tenant's schema.
Tenant identifiers set by trusted components only
The Fineract-Platform-TenantId header selects which tenant's data an API call reads or writes, so it must be set by the API gateway or a trusted client, never copied from end-user input. Ensure the gateway strips any tenant header a caller supplies and sets its own value based on the authenticated session. Test this with requests that carry a tenant identifier belonging to another institution.
HTTPS only with documented SSL settings
The Fineract documentation strongly encourages HTTPS only and documents SSL settings through environment variables such as FINERACT_SERVER_SSL_ENABLED. Confirm that plain HTTP is disabled at the load balancer and application, that certificates are issued and renewed by a process you control, and that internal calls between components are also encrypted where your policy requires it.
Replacing the default mifos login
The README documents a default development login of mifos with a password that must be changed for any real deployment. Remove or replace this account for every tenant before go-live, and confirm that no tenant still accepts the default credentials. Check the same for any sample or seed data loaded during setup.
OAuth2 client scopes per tenant
The README shows OAuth2 and HTTP basic authentication. Where tokens are used, define client registrations and scopes for each tenant so that a client issued for one institution cannot call another's endpoints. Confirm how tenant claims are checked in your chosen setup, because the README example does not settle that question for a multi-tenant design.
Proving tenants stay isolated and fail safely
Before any institution goes live on a shared Fineract platform, the team should be able to show, with recorded evidence, that one tenant cannot read or change another tenant's data and that a fault in one tenant does not stop the others. Configuration review alone does not establish this. The first test is a cross-tenant read and write test. Use valid credentials for tenant A, send requests carrying the Fineract-Platform-TenantId header for tenant B, and attempt to read a client, a loan account and a savings account that belong to B. Then attempt a write, such as creating a client or posting a transaction. Both the read and the write should be refused. Repeat the test in both directions and across every API resource your integrations use, because isolation failures often appear in a single endpoint rather than in the platform as a whole.
The second test covers requests with a missing or unknown tenant identifier. Send calls with the header omitted, with an empty value and with an identifier that does not exist in the tenants database. The platform should reject these requests with a clear error and should not fall back to a default tenant or to a tenant that happens to be first in the configuration. Confirm the default behavior with your Fineract version and your reverse proxy or API gateway, since a proxy that injects or rewrites headers can change the outcome. The third test checks that a failed tenant connection does not take down other tenants. Stop the database for one tenant, or point its connection settings at an unreachable host in a test environment, then confirm that the other tenants continue to serve reads and writes. Record how long the failing tenant takes to return an error and whether connection pools for healthy tenants are affected.
The fourth test is a restore test that returns one tenant without touching others. Take a backup of one tenant's database, damage that tenant's data in a non-production copy, restore only that tenant, and then compare row counts and balances for the restored tenant and for a neighbor tenant that should not change. Confirm that the restore procedure, including any tenants database entries, does not overwrite the others. The fifth test checks that batch jobs for one tenant do not block another. Start a Close of Business run for tenant A and, while it runs, submit transactions for tenant B. Watch lock waits, job duration and whether tenant B's transactions complete on schedule. Because the Close of Business job can run for hours on large deployments, this test should use realistic account volumes in a staging environment.
Each test should be written up with its steps, the expected result, the actual result, the tester, the date and the Fineract version and configuration tested. A mismatch between expected and actual results is a finding, not a note to revisit later. Agree in writing with the owners of each institution what failure looks like and what the platform team will do about it: which errors are acceptable, how long a tenant may be unavailable, who is notified, and whether a tenant is taken offline to protect the others. Keep these agreements with the test records so that auditors and regulators can trace each control to evidence.
How tenancy changes on single node, high availability and Kubernetes
A single node runs the write, read and batch roles on one Fineract instance, which keeps a pilot simple to build and back up. Every tenant is served from the same process, and the tenants database sits on the same PostgreSQL server or on a separate server the team administers. The trade-off is that API traffic and the Close of Business job compete for the same resources, so the batch window must be scheduled around the hours when staff and customers use the system.
- Tenant connections: all tenants resolve through one tenants database, and each API call carries the Fineract-Platform-TenantId header that selects the tenant.
- Batch scheduling: the Close of Business job runs on the instance that serves requests, so a long run can slow responses for every tenant.
- Migrations: Liquibase runs on the only instance, so a failed migration can block the whole platform until it is resolved.
- Backups: one database server holds every tenant, so restore procedures must be tested for a single tenant as well as for the full server.
Confirm the number of tenants, the expected account volume, the nightly batch window and whether the pilot can accept a full outage during upgrades.
The Fineract documentation recommends one write instance, one batch instance and multiple read instances on database read replicas for high load. Each instance type is set through environment variables, so requests and jobs reach the instance designed for them, and reads scale without adding load to the primary database. The design depends on the team controlling routing, replica lag and failover, because a read that returns stale data can confuse staff or customers.
- Tenant connections: every instance reads the same tenants database, and read instances connect to replicas for query traffic.
- Batch scheduling: only the batch instance runs Close of Business, and remote partitioning across worker nodes can be coordinated through ActiveMQ or Kafka.
- Migrations: Liquibase runs only on write instances, so the upgrade sequence must complete on the write node before the other instances change.
- Replication: confirm how PostgreSQL replicas are built, monitored and promoted, and which screens can tolerate replica lag.
Confirm the failover runbook for each tenant, the replica lag level at which reads must go to the primary, the availability of any broker used for partitioning and the team that owns the batch job.
On Kubernetes, instance roles become separate workloads, and Liquibase can run as its own step using the liquibase-only Spring profile. This lets the platform apply database changes once, before application pods roll forward, instead of having each pod attempt to migrate at startup. The Fineract README uses Kubernetes as its example deployment and points to Mifos X as the front end, so the team should treat the repository examples as a starting point to adapt to its own cluster.
- Tenant connections: tenant configuration and database credentials come from the cluster's secrets mechanism, and the tenants database must be reachable from every namespace that runs Fineract pods.
- Batch scheduling: run the batch workload as a single replica so two schedulers cannot start the same job, and confirm how the chosen chart enforces this.
- Migrations: run the liquibase-only profile as a one-off job that completes before the write and read deployments update.
- Scaling: read deployments can scale horizontally, but connection pools multiply with each replica and must be checked against PostgreSQL connection limits.
Confirm that the chart or manifests match the release you select, the rollback path if a migration fails and which team owns the cluster, the database and the batch workload.
In an air-gapped network, Fineract cannot reach public registries, package repositories or external brokers, so every dependency must be mirrored or hosted inside the boundary. The tenants database, PostgreSQL replicas and any ActiveMQ or Kafka broker used for events or remote partitioning must be reachable from the Fineract instances on the internal network. Plan these connections before the build, because a missing route often appears only during the first batch run.
- Tenant connections: the tenants database and every tenant schema must sit inside the boundary and be reachable from the write, read and batch instances.
- Images and artifacts: container images, the PostgreSQL JDBC driver and build dependencies must come from an internal registry and artifact mirror.
- Brokers: external business events are disabled by default, so enabling ActiveMQ or Kafka is a deliberate step that needs internal firewall rules for each endpoint.
- Certificates: HTTPS endpoints should use certificates issued by the organization's internal certificate authority, with trust distributed to every service that calls Fineract.
Confirm the firewall rules for each tenant connection, the process for mirroring each upgrade and whether the batch job can complete using only resources inside the boundary.
What drives tenancy effort and cost, and how to keep each down
This table lists the main drivers of effort and cost in a multi-tenant Fineract platform, with what each one does to the work and the levers that keep it contained. Read each row as a question to put to a partner or your own team, and use the last column to see where standardization pays off. The main takeaway is that most tenancy cost comes from doing each institution's variation separately, so the quote should show effort per driver.
| Driver | Why it changes effort or cost | How to keep it down |
|---|---|---|
| Number of tenants | Each tenant adds configuration, data separation checks, onboarding, access setup and per-tenant testing. Effort grows with every institution or brand added to the shared platform. | Use a standard tenant template and an onboarding checklist so each new tenant reuses proven steps. Ask the quote to show a one-time platform cost separately from per-tenant onboarding. |
| Differences in product catalogs and configuration | Loan and savings products, fees, interest methods and accounting mappings differ by institution. Every divergence needs its own design, configuration and regression testing. | Keep a shared base catalog and record each tenant's deviations as a short, reviewed list. Review new product requests against the base catalog before building them. |
| Data volume per tenant | Larger client and account counts lengthen data migration, reconciliation and Close of Business processing. Heavy tenants can need different sizing and batch planning from light ones. | Size instances and batch partitioning per tenant based on account counts. Ask for migration and batch timing estimates that state the account volumes they assume. |
| Number of integrations per tenant | Payment, KYC, reporting, CRM and notification connections each have their own credentials, mappings, error handling and tests. Integrations often take more effort than the core configuration. | Reuse one integration pattern for common partners, such as a shared event consumer design for external events. Keep tenant-specific adapters isolated so they do not block upgrades. |
| Environments per tenant or shared | Separate development, test and production environments for each tenant multiply infrastructure, data refreshes and test cycles. Fully separate environments cost more to run than shared ones. | Use a shared test tenant for common regression runs, with separate production isolation only where the institution requires it. Ask which environments are included in the fixed scope and which are optional. |
| Regulatory differences between institutions | Different jurisdictions or licence types change reporting, KYC rules, retention and approval workflows. Each variation adds requirements analysis, build work and evidence for assessors. | Group institutions by regulatory profile and build shared controls once. Confirm each tenant's obligations with its own compliance function, since DeployOpen prepares evidence but does not issue assessments. |
| Number of release cycles to support | Fineract publishes official releases quarterly, and each tenant must be tested and upgraded on its own timing if schedules diverge. Frequent divergent upgrades raise regression and Liquibase migration effort on each tenant. | Adopt a single release calendar for all tenants, with one regression suite run against the shared base before tenant-specific checks. Ask the quote to state how many upgrade cycles per year it assumes. |
Running per-tenant upgrades, backups and operating limits after go-live
After go-live, the main operating decision for a multi-tenant Fineract platform is how often every tenant moves to a new release. The Fineract README states that official releases are created quarterly, at the end of each quarter, and that end-of-life releases are archived. Because all tenants share one codebase and one set of instances, the team should plan a single release calendar that every institution or brand follows, unless the team confirms with the Fineract documentation and its own test results that per-tenant versions are supported in its setup. Ask the vendor or project to confirm that position in writing before any tenant asks for a later or earlier version. Plan also for the date when the version you run is archived, since an archived release gets no further fixes from the project.
Each upgrade runs Liquibase database migrations, and according to the Fineract documentation these migrations run only on write instances. On Kubernetes they can be run separately using the liquibase-only Spring profile, which lets the team apply schema changes once in a controlled step rather than during normal startup. Confirm with your own runbook which instance applies migrations, how a failed migration is rolled back, and whether every tenant database is migrated in the same window. Test the full sequence on a copy of production data for every tenant, because a migration that succeeds for one tenant can still expose product or accounting differences in another.
Backup and restore are handled per tenant database, so a restore for one institution should not disturb the others. Define the recovery point and recovery time each tenant requires, schedule backups for the tenants database and every tenant database, and test restores into an isolated environment on a regular cadence. Restore tests should check that a tenant returns to the correct state, including balances and the tenant identifier mapping held in the tenants database, rather than only confirming that the database starts. Agree in advance how a single-tenant restore is coordinated with the other tenants on the same PostgreSQL service, since the Fineract README recommends PostgreSQL as the database.
The Close of Business Day Spring Batch job is the process most likely to limit operations as tenants grow. The Fineract README notes that it can run for several hours on deployments with millions of accounts, and it supports remote partitioning across worker nodes coordinated through ActiveMQ or Kafka. Monitor job duration and failures per tenant, because one large tenant can delay the window for others on a shared batch instance. Confirm with your own load tests how many worker nodes and which broker you need, and set an alert for jobs that overrun the agreed business window. Decide whether the batch instance and its workers are sized for the largest tenant or for the combined load.
Capacity limits apply per instance and must be confirmed rather than assumed. The Fineract documentation describes read, write and batch instance types and recommends one write instance, one batch instance and multiple read instances on database read replicas for high load. Load-test each instance type with realistic tenant mixes, measure connection pool use and batch duration, and record the tenant count and account volume each instance supports. Keep an up-to-date tenant register that lists each tenant identifier, its database, its contact, its release and backup schedule, and its expected volumes. Without that register, capacity planning, restores and upgrade sequencing become guesswork.
Questions buyers ask about multi-tenant Fineract deployment
What drives the cost of running several tenants on one Fineract platform?
The number of tenants matters less than the number of separate operating decisions behind them. Each institution or brand adds its own product catalog, chart of accounts, branding, user roles, integrations and reporting needs, and each of these needs design, configuration and testing. Shared infrastructure is a recurring cost that grows with transaction volume, account count and the number of running instances (read, write and batch). One-time costs include tenant onboarding design, data separation checks and the first set of tests. Recurring costs include infrastructure, monitoring, upgrades and support. Ask any partner to split its quote into platform work that serves all tenants and tenant-specific work, because that split shows how the cost will change as you add institutions.
How long does it take to add a new tenant to an existing Fineract platform?
The answer depends on what the new tenant needs beyond a new database entry. Registering a tenant in the tenants database and routing its API calls with the tenant identifier is the technical core, but it is rarely the longest step. Product configuration, ledger mapping, staff access, integrations and migration of any legacy data usually take more time, and each depends on decisions from the institution. No duration should be accepted without a written scope listing those steps. Ask the partner which steps it has done before on the same platform version, what it needs from your team in each step, and which steps can run in parallel.
What does the institution's own team need to contribute to a multi-tenant Fineract project?
Each tenant needs named owners on the institution's side, and the work stalls without them. Product owners decide loan and savings terms, fees and delinquency rules. Finance confirms the chart of accounts, product-to-ledger mapping and reconciliation rules. Security approves identity, role design, API exposure and credential handling. Integration owners provide the details of payment, reporting and CRM systems that will consume data. Operations staff own the Close of Business process and incident response after go-live. Before signing, ask the partner to list these roles, the hours each role will need, and the decisions that must be closed before build starts.
Can a capable in-house engineering team build multi-tenant Fineract without a partner?
A capable team can build it, but the question is whether it has time to build and keep running it. The Fineract project documentation notes that a production deployment can be complex, costly and time-consuming, and that the project does not provide a comprehensive production deployment guide. Your team will need experience with Java services, PostgreSQL operations, container platforms, identity integration and accounting logic in a core banking context. It will also need to schedule quarterly platform releases against live tenants. Assess your team against that list, estimate the staff time it would take away from other work, and compare that with a fixed-scope quote for the same deliverables.
What should a fixed-scope quote for multi-tenant Fineract deployment list?
A useful quote lists deliverables, assumptions and responsibilities, not only a total. It should name the platform components in scope, such as the tenants database, the instance layout for read, write and batch processing, the database setup, and the environments for testing and production. It should list each tenant in scope and the configuration work for each, the integrations and data migrations included, the testing and sign-off criteria, and the documentation handed over. It should also state what the institution must provide, the upgrade and support terms that apply after go-live, and what is excluded. Ask for any change to scope to be priced in writing before work proceeds.
How does the tenant identifier keep one institution's data separate from another's?
Fineract separates tenants by routing each API request to its own tenant database connection. The client sends the Fineract-Platform-TenantId header with each call, and the platform uses the tenants database to select the matching connection. This establishes the boundary at the application layer, but it does not replace database-level controls. Engineers should check which credentials each tenant connection uses, whether tenant databases sit on separate servers or schemas, how backups are scoped per tenant, and how logs and audit trails record the tenant. Confirm these design choices against the Fineract documentation for your version and against your own security policy before go-live.
Can each tenant be upgraded on its own schedule in a shared Fineract platform?
Usually not fully, because tenants share one codebase and one platform lifecycle. Fineract publishes official releases quarterly, and database migrations are managed through Liquibase, which runs only on write instances according to the project documentation. Upgrading the platform therefore affects every tenant that runs on it. Plan a shared upgrade calendar, regression tests for each tenant's products and accounting, and a rollback approach. If one institution needs a different release timing, confirm with the partner whether that means a separate platform deployment, and what that does to cost. Ask for the upgrade process in writing before you commit.
How DeployOpen scopes, builds and hands over multi-tenant Fineract
DeployOpen plans and implements Apache Fineract inside your own cloud accounts, data centers or air-gapped networks, so each institution or brand runs against a tenant configuration you can inspect and audit. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
How we scope
- Inventory every institution or brand, its products, currencies and regulatory obligations before choosing a tenancy model.
- Document the tenants database layout, tenant identifiers each client application must send, and who owns each tenant.
- Agree in writing which per-tenant data separation, upgrade cadence and operating limits are in and out of scope.
- Ask for the written scope to name the environments, instance types and backup targets that will be delivered.
How we build
- Configure the tenants database and connection settings, then verify that each tenant resolves to its own PostgreSQL database.
- Set the Fineract-Platform-TenantId header handling at the gateway so requests cannot reach an unintended tenant.
- Deploy read, write and batch instances per environment, with Liquibase migrations confined to write instances.
- Test cross-tenant access, data isolation and per-tenant configuration changes before any tenant goes live.
How we hand over
- Deliver runbooks for adding a tenant, rotating credentials and running a per-tenant upgrade on a staging copy first.
- Document the tenant map, environment variables, database roles and the evidence trail for each tenant's access controls.
- Walk your platform, database and security staff through operations, then record who owns each tenant after handover.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer, scoped separately from the build.
- Plan upgrades around Fineract's quarterly releases, with regression testing of each tenant's products and accounting.
- Confirm with us what a retainer covers, including response expectations and which tenants and environments it applies to.
