Why an Apache Fineract 1.14 to 1.15 upgrade cannot wait
A self-hosted Fineract 1.14 deployment that is end of life should move to 1.15.0, the current stable release, and the move should be planned now rather than deferred. Official Fineract releases are created quarterly, at the end of each quarter, under the Apache Software Foundation release policy, and end-of-life releases are archived. An instance on 1.14 therefore has no maintained release line behind it, and each quarter that passes adds more change to the eventual upgrade. Start by inventorying your running version, your database platform and every custom module or script that touches the core, because those items decide how much work the upgrade involves.
The path the outline describes is a single step from 1.14 to 1.15. Confirm that against the 1.15.0 release notes and upgrade notes before you commit to a window, because your own customizations, environment variables or deprecated settings may add steps. The Mifos X web app is the front end most teams run with Fineract, and its version must match the backend. That makes the front end part of this change, not a later task. Identify the web app release tagged for 1.15.0, check the environment variables it expects, and schedule staff acceptance testing in the same window as the backend migration.
The Fineract README states that the project does not provide a comprehensive production deployment guide and warns that production deployments can be complex, costly and time-consuming. The upgrade plan therefore has to be written by your team or by a partner you engage under written scope. It should cover a verified backup and restore, the order of Liquibase migrations, the rollback decision point, regression testing of products, accounting and close of business, and the sign-off criteria for go-live. Read the project's GitHub repository for the release history, then document every decision before the change window opens.
What changes between 1.14 and 1.15 and what each change requires
This table lists what the move from 1.14 to 1.15 touches and what each change asks of your team, covering products, accounting, COB, integrations and the front end. Check each row against your own configuration and integrations, because the 1.15.0 release notes and repository hold the authoritative list of changed code, changesets and deprecations. The main takeaway is that the SQL injection fixes and the startup schema changes carry the most risk, so both need a rehearsal on a production-sized copy before go-live.
| Change | Impact on products, accounting, COB and integrations | Action the team must take |
|---|---|---|
| Three SQL injection fixes | Queries behind some endpoints, reports or custom code may behave differently with unusual input. Products and ledger postings should be unaffected unless a fix touches their code path. | Map each fix in the 1.15.0 release notes to your endpoints and custom code. Replay your existing integration payloads and report calls in a test environment. |
| Liquibase schema changes applied at startup | Changesets run only when a write instance or the liquibase-only profile starts. Read instances do not apply them, so an uncoordinated restart can leave the schema and code out of step. | Take a verified database backup, run the liquibase-only job once before rolling application pods, and confirm the changeset list in the repository. |
| Instance rollout order | Write, batch and read instances on mixed versions may fail against a changed schema, which disrupts scheduled jobs and reads during the window. | Sequence the upgrade: migrate the schema first, then roll write, batch and read instances. Confirm mixed-version support with the project before any overlap. |
| Loan and savings products | Product definitions, schedules, interest accrual and charges depend on the core calculation code and may shift with schema or default changes. | Regression test each active product through disbursement, repayment, accrual, charge, closure and write-off. Compare results with a 1.14 baseline on the same data. |
| Accounting and general ledger | Journal entries, accounting mappings and feeds to an external ERP are the outputs finance teams reconcile. A change in posting behavior affects month-end. | Produce trial balances and journal listings before and after the upgrade on a copy. Reconcile differences to the chart of accounts and your ERP feed. |
| Close of Business (COB) job | COB can run for hours on large deployments and supports remote partitioning. Any change to batch steps shifts completion time and posting results. | Time a full COB run on production-sized data after the upgrade. Confirm completion, posting totals and partition settings on the batch instance. |
| Integrations and business events | API clients, reports and external consumers depend on request and response behavior. Business event publishing is disabled by default, so only enabled setups are affected. | Run existing API clients and generated code against 1.15. If events are enabled, confirm the ClientCreated and other payloads in the release notes. |
| Mifos web app version | The front end is released against Fineract versions. A mismatched web app can break staff workflows even when the backend upgrade succeeds. | Select the web app release tagged to 1.15.0, check its environment variables, reapply custom UI changes and retest staff workflows. |
| Database platform and deprecations | PostgreSQL is the recommended database, and MariaDB and MySQL are deprecated under FSIP-9. Deprecated settings may stop working after the upgrade. | Confirm the database platform first. Check the 1.15.0 release notes for deprecated settings and compare them with your environment variables and tenant configuration. |
How the supported path from 1.14 to 1.15 is confirmed
Start by confirming that 1.15.0 is still the path you should take. The Fineract website lists 1.15.0 as the current stable release, and its 1.15.0 documentation at the platform documentation describes the configuration you will need to match. Because the project creates official releases quarterly, check the release list and the repository on GitHub before you plan the window, since a newer release may have shipped while you were preparing. Then read the repository's release and end-of-life notes for 1.14 to confirm that your starting build is no longer supported. The README states that end-of-life releases are archived, so confirm the status of your exact build rather than relying on the minor version label alone, and record the commit or tag you run today.
Next, confirm the database platform before you fix the upgrade scope. The README recommends PostgreSQL and states that MariaDB and MySQL are deprecated under FSIP-9, so an upgrade that also changes the database engine is two projects. If your tenant databases run on MariaDB or MySQL, treat the move to PostgreSQL as a separate migration with its own schema, data and reconciliation plan, and do not mix it into the 1.15 change. Confirm which database version your current build and the 1.15.0 documentation expect, and check the official Docker image, which ships only the PostgreSQL JDBC driver, against your deployment.
Finally, decide between upgrading in place and standing up a parallel environment. An in-place upgrade is shorter and keeps configuration, but it runs Liquibase migrations against live data and leaves little room to return to 1.14 if a regression appears. A new environment restored from a recent backup lets you run the migration, the regression tests on products, accounting and COB, and the Mifos web app match before cutover, at the cost of duplicate infrastructure and a data synchronization step. Choose based on how much data changes between the restore point and cutover, and confirm the rollback path with your own team before you commit.
What to back up and inventory before touching the database
Five preparation items decide whether a Fineract 1.14 to 1.15 upgrade can be rolled back at all. Each one answers a specific question you will face if a migration or regression test fails, so treat them as gates that must be cleared before the first Liquibase run.
Verified database backup and restore
Take a full backup of the tenant databases and the tenants database, then restore it into a separate environment and confirm Fineract starts and reads accounts. A backup that has never been restored is not a rollback plan. Liquibase changesets run against the schema in place, so a restored copy is the only reliable way back if a migration stops partway. Record the restore time you measured, since it sets the outage window you can accept.
Inventory of custom core edits
List every custom change that edits Fineract core sources, including patched services, altered Liquibase files and forked builds. Core edits are the most likely cause of a merge conflict or a failed changeset during the move to 1.15. Confirm each one still applies to the 1.15.0 source tree, and decide whether it is removed, rebased or kept as a documented exception. Without this list, a regression looks like a Fineract defect when it is your patch.
Custom jobs, events and business steps
Inventory custom Spring Batch jobs, business steps, processors and external event listeners, including ClientCreated publishing to ActiveMQ or Kafka if you enabled it. The Close of Business Day job is the most sensitive of these, because it can run for hours on large portfolios. Record which steps depend on specific table columns and which consumers read event payloads. Those consumers must be tested against 1.15 before cutover, or they can fail silently after the switch.
Tenant configuration from the tenants database
Export tenant records from the tenants database, including tenant identifiers, connection settings and any tenant-specific properties. Fineract routes each request through the Fineract-Platform-TenantId header, so a wrong or missing tenant entry can make one tenant appear empty while others work. Keep a copy of this configuration with the database backup, so you can recreate the tenant mapping if the upgrade environment is rebuilt.
Mifos web app version and environment variables
Record the Mifos X web application version currently deployed and every environment variable set on the Fineract and web app containers, including instance-type settings and SSL variables such as FINERACT_SERVER_SSL_ENABLED. The web app must be matched to the Fineract release, so a rollback needs both versions and their configuration. Store these values in version control with the deployment manifests, not only in the running cluster, so you can reproduce the pre-upgrade state exactly.
Staging sized for a COB run
Build a staging environment with a copy of production data volume and run a full Close of Business Day job on 1.15 before any production change. Staging that holds a few test clients will not show whether the job finishes inside your batch window. Compare its duration with the production run you recorded, and confirm the database instance class, connection limits and worker count match production. This test gives you the timing evidence needed to schedule the production upgrade.
Upgrade sequence with checks and rollback points
This sequence moves a Fineract 1.14 deployment to 1.15 in an order that keeps a known-good state available at every stage, so each change can be verified and reversed before the next one starts. It separates the schema migration from the application rollout and ties the Mifos web app version to the backend release.
Freeze change windows and confirm scope
Agree a change freeze with the business owners for products, accounting and any open end-of-day work, and confirm which tenants and integrations are in scope. Record the current running versions of the backend, the Mifos web app, and every integration consumer, including external event subscribers such as ActiveMQ, JMS or Kafka if they are enabled. Done when the freeze is documented and nobody can change configuration or product definitions during the window. Rollback point: the freeze can be lifted at any time before step two without any system change.
Back up the database and configuration
Take a full PostgreSQL backup of the tenant databases and the tenants database, and export the environment variables, deployment manifests and any custom code or build artifacts that edit core sources. Test that the backup can be restored into a separate database and that row counts for key tables match the source. Done when a restore test has succeeded and the backup location and retention are recorded. Rollback point: this backup is the reference for restoring the schema if a later Liquibase step fails.
Deploy 1.15 to a staging tenant
Restore a recent copy of production into staging, then deploy Fineract 1.15.0 and the matching web app build against it. Confirm the application starts, the Liquibase changesets apply cleanly, and the tenant resolves through the Fineract-Platform-TenantId header. Review the three SQL injection fixes in the 1.15 release notes against any custom queries or extensions you run. Done when staging starts without errors and the regression suite in a later step can run against it. Rollback point: staging can be rebuilt from the backup without affecting production.
Run the liquibase-only profile against a write instance
Liquibase migrations run only on write instances, so run the liquibase-only Spring profile as a separate job against the production write database before any application instance is upgraded. On Kubernetes, this job runs ahead of the rollout while the old application pods keep serving traffic on the 1.14 schema. Confirm the job exits successfully, the changelog table shows the expected 1.15 changesets, and the schema matches what staging produced. Rollback point: if the job fails, restore the schema from the step two backup and keep the 1.14 application running.
Bring up write, batch and read instances
Start the 1.15 write instance first, then the batch instance, then the read instances against the database read replicas. Use the documented instance type environment variables so that only one write instance is active and Liquibase does not run on batch or read instances. Check health endpoints, confirm the batch instance runs the Close of Business Day job on its schedule, and confirm read instances serve queries without writing. Done when all instance types report healthy and the first COB run completes. Rollback point: route traffic back to the 1.14 instances, which still work against a schema that 1.14 can read only if you have not yet applied non-backward-compatible changes, so verify that against the release notes before cutover.
Match the Mifos web app to the backend
Deploy the Mifos X web app release that matches Fineract 1.15, check the environment variables it expects against the backend configuration, and confirm that any custom UI changes still load and submit correctly. Walk through the staff workflows that matter most to the business, such as client onboarding, loan disbursement and savings transactions. Done when the web app loads against the upgraded backend and the sampled workflows complete without errors. Rollback point: the web app can be pointed back to the previous build while the backend is held at 1.15 only if the old build is confirmed compatible, so do not mix versions without that check.
Run regression checks on products, accounting and COB
Execute a regression pass covering loan and savings products, ledger postings and journal entries against the chart of accounts, interest and charge calculations, and a full Close of Business Day run. Compare the results with the outputs recorded in staging and with the pre-upgrade production baseline for a sample of accounts. Check that outbound event consumers and integrations still receive the expected messages. Done when every test case has a recorded pass or a signed-off exception. Rollback point: if material differences appear, keep the business freeze in place and use the step two backup with the step four runbook to restore the prior state.
Lift the freeze and record the release
Once regression is signed off, lift the change freeze, record the final versions of every component, and store the backup reference, job logs and test evidence with the change record. Schedule the next review point and confirm that monitoring, alerts and backups run against the new instances. Done when the change record is complete and the operations team confirms monitoring is active. Rollback point: after the freeze is lifted, rollback requires a planned reversal, so keep the step two backup retained for the period your change policy requires.
Regression testing products, accounting and COB before go-live
The regression run is where a 1.14 to 1.15 upgrade proves that the money still moves correctly, so the scope should be set before the upgrade is rehearsed. Cover three areas: loan and savings product behavior, journal postings and ledger mapping, and a full Close of Business Day (COB) run. For each loan and savings product in use, replay representative accounts through disbursement, repayment, interest accrual, charges, fees and closure, then compare balances and schedules against the pre-upgrade baseline from the same data. Journal entries should be reconciled account by account against the chart of accounts and the mapping that feeds your general ledger, because a mapping that still resolves but posts to the wrong account will not raise an error on its own.
COB needs its own timing test. The Fineract README notes that the Close of Business Day Spring Batch job can run for several hours on deployments with millions of accounts, and that it supports remote partitioning across worker nodes coordinated through ActiveMQ or Kafka. Run COB on a copy of production-sized data, on the same worker topology you plan to use, and record duration and any failed partitions. Confirm the figures you need for your own capacity plan with your own data, since the project does not publish a general estimate. Staff workflows in the Mifos web app, which must match the Fineract version, should be tested end to end by the people who use them daily.
External event publishing is disabled by default, so any downstream system that relies on events such as ClientCreated will receive nothing until someone turns it back on. Treat re-enabling the event broker configuration as a deliberate change: confirm the broker or Kafka topic, test that each consumer receives and handles the events it expects, and check how duplicates or gaps are handled during the cutover window. Record which integrations were tested, by whom and against which build, so the sign-off is traceable.
What makes a Fineract 1.14 to 1.15 upgrade longer or costlier
This table lists the factors that most often extend or raise the cost of moving from Fineract 1.14 to 1.15, with why each matters and what to check in your environment. Read it before scoping, because each row changes how much custom code, testing and coordination the upgrade needs. The main takeaway is that the upgrade is rarely limited by the version change itself and is usually driven by your customizations, integrations and test capacity.
| Driver | Why it matters | What to check |
|---|---|---|
| Custom code against core sources | Patches or edits to Fineract core classes must be rebased onto 1.15 and may conflict with the security fixes or Liquibase changes. | List every change to core sources, not just custom modules, and confirm which ones the three SQL injection fixes touch. |
| Number and complexity of integrations | Each system that calls the REST API, consumes business events or reads the database must be retested, and any API change affects its contract. | Count integrations, note which use generated clients, and confirm whether event publishing is enabled, since it is off by default. |
| Data volume and COB duration | Liquibase migrations and the Close of Business job both scale with data, so longer runs extend the cutover window and the test cycles. | Measure current COB runtime on a production-sized copy and ask whether remote partitioning is already configured. |
| Number of tenants | Fineract is multi-tenant, so each tenant database needs its own migration check, reconciliation and regression pass. | Confirm the tenant count, whether tenants share settings, and whether any tenant has unusual products or accounting setups. |
| Web app customizations | A Mifos web app must match the Fineract version, so custom screens or templates may need rework and staff workflows need retesting. | Confirm the web app version in use, list custom UI changes, and check the Mifos web app release tagged to 1.15. |
| Database platform | MariaDB and MySQL are deprecated under FSIP-9, so an upgrade on those engines may need a separate migration decision before or after the version move. | Confirm the current engine. If it is MySQL or MariaDB, plan the PostgreSQL move as its own workstream with its own sign-off. |
| Team availability for testing | Regression testing of products, accounting and COB needs business and finance staff, not only engineers, and delays there push back the cutover. | Name the testers for loan and savings products, accounting closures and COB reconciliation, and book their time before scheduling. |
Questions teams ask before upgrading Fineract 1.14 to 1.15
What drives the cost of a Fineract 1.14 to 1.15 upgrade?
The main cost drivers are the amount of custom code and configuration, the number of integrations that call the REST APIs or read the database, how many loan and savings products and accounting mappings must be retested, and the deployment topology. Cost usually splits into assessment, environment preparation, the upgrade itself, regression testing and handover. Ask for the quote to list each of these as a separate line, to state whether regression testing is included, and to separate one-time work from any recurring support. DeployOpen does not publish a price list. A quote follows from the written scope, so the more complete your inventory of custom code and integrations, the more precise that scope can be.
How long does a Fineract 1.14 to 1.15 upgrade take?
Duration depends on the number of environments, whether the platform runs one write instance, one batch instance and read instances, how Liquibase migrations are executed, and how much regression testing your products, accounting and end-of-day processing require. The Fineract README notes that the Close of Business Day job can run for several hours on deployments with millions of accounts, so testing on a large book of accounts takes longer than testing on a small sample. Custom code and the number of integrations also extend the schedule. No general duration applies to every deployment. Confirm the timeline in the written scope, including the staging runs and the change window needed for the production cutover.
What must our team provide for the upgrade?
The team needs to provide access and information that only the organization holds. This typically includes:
- A recent copy of the production database in a staging environment, with data handling approved under your own policies
- Current configuration, environment variables and deployment manifests for every Fineract instance
- Repositories for any custom modules, jobs, business steps or integrations
- An inventory of systems that call Fineract, read its database or consume its business events
- Test cases or a named business owner for products, accounting and COB results
- Cluster or cloud access, a change window and a decision-maker who signs off the cutover
Without these inputs, the assessment and the regression scope will be incomplete, which affects both cost and timing.
Can our internal team run the Fineract upgrade without a partner?
An internal team can run the upgrade if it already has working skills in several areas: Fineract configuration and its REST API, PostgreSQL administration, container and Kubernetes operations, and Liquibase migrations. The team also needs a documented regression plan covering products, accounting and COB, and enough capacity to run that plan alongside its normal operations. Evaluate whether anyone has completed a Fineract upgrade before, who will be on call during the cutover, and whether the same people are needed for other projects. A useful first step is a written self-assessment against those areas. Where gaps exist, a fixed-scope engagement can cover only the parts you choose to outsource, and the scope document will state exactly what is included.
How does rollback work if a Fineract migration fails?
Rollback planning starts before the migration runs. Take a verified database backup, prove that you can restore it on a copy of the environment, and keep the previous application image or deployment definition available. Liquibase applies schema changes in a forward direction, so returning to the earlier release often means restoring the database from backup rather than reversing individual changesets. Confirm this approach against the 1.15 release notes and the changelogs for your deployment. Rehearse the full sequence, including the time a restore takes, in a staging environment before the production window. The written scope should name the rollback steps, the decision point at which rollback is triggered and who makes that call.
Does the Mifos web app have to change when Fineract moves to 1.15?
The web app does not change automatically, but it should match the Fineract release it talks to. The Fineract README names the Mifos X web application as the front end used in its Kubernetes example, so many deployments depend on it. Check which Mifos X web app release is tagged to Fineract 1.15, review the environment variables it expects, and compare any custom UI changes against that release. Then test the staff workflows that matter most, such as client onboarding, loan disbursement, savings transactions and reporting. If your front end is not the Mifos web app, confirm with its maintainers which Fineract versions it supports. Include front-end testing in the written scope.
What does a fixed-scope quote for this upgrade cover?
A fixed-scope quote covers the named environments, the upgrade steps, the regression areas that are in scope, the handover documentation and the acceptance criteria. Most engagements are fixed-scope, which means scope, deliverables and timelines are agreed in writing before work starts. A well-written quote also states what is excluded, such as new feature development, integrations that were not inventoried, or changes to custom code beyond the upgrade. Ongoing support, upgrades and continuous testing are available as retainers and are quoted separately. Ask for the quote to list the assumptions it relies on, such as the availability of a staging copy of the database, so that any change to those assumptions can be discussed before it affects the schedule.
When to roll back and when to proceed
Plan to restore the pre-upgrade database backup if the upgrade fails after Liquibase has run. Liquibase applies schema changes as it goes, so a failed 1.15 migration can leave the database partly changed and no longer matching the 1.14 application. Rolling back the application binaries alone is not a safe reversal. Decide the criteria before the window opens: a migration that fails or stops partway, a schema state that does not match the expected changelog entries, a failed smoke test on products, accounting or COB, or a data reconciliation mismatch that cannot be explained within the window. Set a go or no-go checkpoint after the migration step and another after regression testing, and name the person who makes each call.
Forward fixes make sense only when the problem is confined to the application layer, the schema is complete and verified, and the fix can be tested in the same window without touching data already written under 1.15. Confirm this with the Liquibase changelog for 1.15 before the window, so you know exactly which changesets run, which tables they touch, and whether any are hard to reverse. Ask the vendor or project for the rollback guidance for that release, and confirm that your restore procedure has been rehearsed against a copy of production data, including how long a restore takes and who has access to the backup.
Record every decision in the change log: the backup identifier and its verification result, the Liquibase state before and after each step, the start and end times of each checkpoint, the test results that drove each go or no-go, the approver for each call, and any transactions written between the backup and the rollback point. If you restore, record what data written after the backup will be re-entered or reconciled. This record is what your change board and auditors will ask for.
How DeployOpen scopes, delivers and supports the Fineract upgrade
DeployOpen plans and delivers the move from end-of-life Apache Fineract 1.14 to 1.15 inside your own infrastructure. The work starts with a written scope covering the three SQL injection fixes, Liquibase migrations for your instance types, regression testing of products, accounting and COB, and the matching Mifos web app version.
How we scope
- The written scope names your Fineract 1.14 deployment, database platform, instance types and every custom extension to be reviewed.
- Engagements are fixed-scope, so deliverables and timelines are agreed in writing before the upgrade work starts.
- The scope also records the Mifos web app version to pair with 1.15 and the staff workflows to retest.
How we build
- We review the three SQL injection fixes against your custom code, API clients and any direct database access.
- We run Liquibase migrations on a staging copy first, setting write and liquibase-only instance roles to match your topology.
- Regression tests cover loan and savings products, journal postings, and Close of Business Day runs against representative data.
How we hand over
- Deliverables include the upgrade runbook, the migration log, rollback steps and the regression results for your records.
- Your operations team rehearses the cutover and the rollback before production, using the documented steps.
- Configuration, secrets and environment variables are documented so the next upgrade does not depend on one person.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after the upgrade closes.
- Retainer work can cover watching the next quarterly Fineract release and planning its upgrade window.
- Issues found in production after cutover are handled through the same written scope process.
