Why the Mifos X web app must match your Fineract release
If your team is moving Fineract forward and also runs a Mifos X web front end, the web app is tied to a specific Fineract version and must be upgraded in step with the backend. Fineract is headless: it exposes REST APIs and does not ship its own user interface, so the web app is a separate component that calls those APIs. A newer backend can change endpoints, responses or behavior that an older front end expects, so the supported sequence is to upgrade the backend first, then move the web app to the release built for that Fineract version.
The Apache Fineract project creates official releases quarterly, at the end of each quarter, under the ASF release policy, and archives end-of-life releases. The Fineract website lists 1.15.0 as the current stable release. Because the cadence is quarterly, a front end that was current when you last deployed can fall behind within a few releases, so the alignment check belongs in every upgrade plan rather than being done once. Confirm the exact pairing in the web app's release list and its README before you choose a tag, since the tag names carry the Fineract version they target.
Before the cutover, confirm three things with the vendor and the web app release notes: which web app tag targets your target Fineract version, whether the FINERACT_API_URL and FINERACT_PLATFORM_TENANT_IDENTIFIER settings or their defaults changed, and whether the tenant identifier still matches the Fineract tenants table. Plan a staging run that exercises the web app against the upgraded backend, and record any front-end version that cannot yet be paired with the target backend as a blocking item for the production window.
What changes on the front end when the web app and backend move together
This table compares the web app tag, its configuration settings and the Fineract 1.15.0 backend changes that affect front-end work. Read each row as a question to answer before the upgrade window, and treat anything marked for confirmation as an open item until the release notes settle it.
| Change | Impact on staff and integrations | Action needed |
|---|---|---|
| Mifos X web app v1.0.0-fineract1.14 (published December 23, 2025) | This tag is built for the Fineract 1.14 API. Staff screens that call endpoints added or changed in 1.15.0 may fail or show incomplete data if the tag is kept after the backend moves. | Confirm in the release notes which web app tag pairs with Fineract 1.15.0. Do not assume the 1.14 tag works against 1.15.0. |
| FINERACT_API_URL setting | Points the web app at the Fineract backend. After a backend move, a stale host, path or scheme can break logins and every screen at once. | Update the value to the upgraded backend endpoint in each environment and test login from a staff workstation. |
| FINERACT_PLATFORM_TENANT_IDENTIFIER setting | Must match a row in the Fineract tenants table. A mismatch shows staff a login or tenant error even when the backend is healthy. | Check the identifier against the tenants table in every environment, including any new tenant added during the upgrade. |
| Fineract 1.15.0 Liquibase migrations | Schema changes apply before the new backend serves traffic. Staff screens reading changed database structures may behave differently until the migration completes. | Run the migration on a write or liquibase-only instance first, then confirm the web app loads product and client pages. |
| Fineract 1.15.0 security fixes (SQL injection) | Some search and filter behavior in the API may change. Saved filters or staff reports that depend on odd input patterns may return different results. | Confirm the affected endpoints in the 1.15.0 release notes and rerun staff search and report workflows. |
| Custom UI changes in the web app fork | Customizations built on the 1.14 tag may conflict with the new tag. Merge conflicts can hide changed labels, fields or validation rules. | List every custom screen and field, rebase them onto the chosen tag, and retest each one against the new backend. |
| Response shape and field changes in the API | Front-end forms may fail to save or display fields if response shapes differ from what the web app expects. | Confirm response changes in the Fineract release notes and in the web app release notes for the matching tag. |
| Staff workflow regression testing | Daily tasks such as client onboarding, loan approval, savings posting and end-of-day checks are where front-end and backend mismatches surface first. | Run a scripted test pass with branch staff roles before cutover, and record each result against the web app and Fineract versions. |
What to inventory and back up before changing the web app
Changing the front end is easier to reverse when the current state is written down first. The items below cover what you can roll back to, what the new build must be pointed at, and how you will know staff can still do their jobs.
Back up the current build and configuration
Keep a copy of the deployed web app artifact or container image in use today, along with its environment configuration, such as FINERACT_API_URL and FINERACT_PLATFORM_TENANT_IDENTIFIER. Store these in version control or your registry with the date and the Fineract version they were paired with. Without this record, a failed upgrade means rebuilding the old front end from memory, which is slow and error-prone under pressure.
Inventory custom UI changes and branding
List every change made to the stock web app: logos, colors, labels, custom forms, added pages and patched source files. Note which ones were made by editing the source and which by configuration. Source edits are the changes most likely to conflict with a new web app release, so they need a named owner and a decision on whether to keep, rework or drop each one.
Check tenant identifiers against the tenants table
Confirm that the tenant identifier set in the web app matches the entry in the Fineract tenants table exactly, including case. A mismatch can surface as a login or data-loading failure that looks like an upgrade fault. Record the identifier for each environment, because staging and production often use different tenants and a copied value can point a test build at live data.
Build a staging environment on a restored backend
Stand up a staging web app that points at a restored copy of the Fineract backend and database, not at production. Restore the backend to the target Fineract release first, so the front end is tested against the same API it will meet in production. Confirm that the restored environment is isolated from production integrations, such as payment or notification connectors, before any user signs in.
Write the list of staff workflows to test
Document the tasks each role performs daily in the web app, such as client onboarding, loan application and approval, disbursement, repayment, savings transactions, and end-of-day reports. Assign each workflow a tester and an expected result. This list becomes the acceptance checklist for the upgrade, so it should cover the screens your branches actually use, not only the default demo path.
How to sequence the web app upgrade with the Fineract upgrade
This sequence keeps the Mifos X web app and the Fineract backend on matching versions at every stage, so staff never sign in to a front end that expects a different API. It also leaves a tested rollback point before production cutover.
Confirm the target Fineract and web app pair
Before any change, the platform owner and the web app lead confirm the target Fineract release and the openMF/web-app release tagged to it. Check the release tag names on the openMF/web-app releases page, and note the Fineract version the front end was built for. The web app release v1.0.0-fineract1.14 is the tag that pairs with Fineract 1.14, so confirm the tag that matches your target backend rather than assuming the latest tag fits. Output: a written version pair signed off by both owners. Done when the pair is recorded in the change ticket.
Back up the backend and the current web app
The database owner takes a full backup of the Fineract tenant databases, including the tenants database, and the current web app build artifact and its environment configuration are copied to a versioned location. Record the exact build, image digest or static asset bundle that serves staff today. Done when a restore of the database backup has been test-run on a separate instance and the web app artifact can be redeployed without rebuilding it.
Rebuild the web app against the target environment
The front-end engineer checks out the matching tag and rebuilds the web app with the target environment values. Set FINERACT_API_URL to the address of the upgraded Fineract API, and set FINERACT_PLATFORM_TENANT_IDENTIFIER so it matches a row in the Fineract tenants table. Review any custom UI changes that were merged onto the previous build and reapply them on the new tag, then record the build output. Done when the build completes and the configuration values are written into the build record.
Deploy the pair to staging and smoke test
Deploy the upgraded Fineract backend and the rebuilt web app to a staging environment that mirrors production's tenant setup and authentication. Sign in with a named staff account, confirm the tenant loads, and confirm the web app calls the intended API host and not a previous environment. Check the browser console and network calls for failed requests or version mismatch errors. Done when the sign-in and tenant load succeed and no API call fails in the smoke test.
Run the staff workflow test pass
Staff from each business function run their daily workflows on staging, using scripted scenarios written from production use. Typical scope includes client creation and KYC document upload, loan and savings account creation and disbursement, transactions and teller operations, and reports that staff rely on. Compare outputs with the pre-upgrade results for the same test data, and log every difference, including layout or label changes caused by custom UI work. Done when each scripted scenario has a signed result and every open defect is either fixed or accepted by the business owner in writing.
Cut over the backend and web app together
During the agreed change window, the team applies the backend upgrade, including the Liquibase steps described in the linked sibling topics on running migrations on write or liquibase-only instances, and then deploys the tested web app build. Keep the two deployments in the same window so that no staff session runs the old front end against the new API. Run the smoke test from step four in production. Done when production sign-in, tenant load and a sample transaction succeed and the change record shows both versions.
Hold the rollback point until sign-off
Keep the previous web app build, its configuration, and the pre-upgrade database backup available until the business owner confirms production is stable. Define in advance who can trigger a rollback, what conditions require it, and the order of steps: redeploy the previous web app build first, then restore the backend if the database schema requires it. Confirm the rollback path was rehearsed in staging. Done when the owner signs off and the retained artifacts are moved to the archive with a dated record.
How FINERACT_API_URL and tenant identifiers connect the web app to Fineract
The web app does not hold any banking data itself. Every screen a staff member sees is produced by calls from the browser to the web app, and from the web app to the Fineract REST API. Two settings decide where those calls go and which tenant's data they touch: FINERACT_API_URL, which points the web app at the Fineract backend, and FINERACT_PLATFORM_TENANT_IDENTIFIER, which the web app sends to Fineract so that Fineract can select the right tenant database. The web app README requires that the tenant identifier align with the Fineract tenants table, so this pair of values must be checked on every environment after a backend upgrade, not only the first one.
Fineract is multi-tenant. Each API request carries a Fineract-Platform-TenantId header, and Fineract uses that value to look up the matching entry in its tenants database before it opens a connection. If the identifier does not match a row in that table, the request cannot be routed to a tenant, and login or data calls fail. The failure can look like a broken web app even though the backend is healthy, so staff may report a login problem that is really a configuration mismatch. Confirm the identifier against the tenants table in each environment, and do not assume that a staging value carries over to production, since the tenant names and databases are set per deployment.
For each environment, check the value of FINERACT_API_URL against the address the web app container can actually reach, then confirm that any reverse proxy, load balancer or ingress in front of Fineract forwards the Fineract-Platform-TenantId header unchanged. A proxy that strips or rewrites custom headers will cause the same failure as a wrong identifier. Read-replica or read-instance routing should also be tested, because a request that reaches a different instance must still resolve the same tenant. Write these values into the upgrade runbook for staging, production and any replica path, and record which web app release tag each one was tested against.
How custom UI changes affect the upgrade path
If you run the published Mifos X web app image or release without source changes, the upgrade is mostly a version decision. Each web app release is tagged against a Fineract backend version, so the work is to select the tag that matches your target Fineract release, then point the app at the backend. The release v1.0.0-fineract1.14 shows how the tag names the backend line it targets. Your main job is configuration and regression testing, not code merges.
- Pick the matching tag: Choose the web app release tagged for your target Fineract version rather than the newest tag by default.
- Check runtime settings: Confirm
FINERACT_API_URLandFINERACT_PLATFORM_TENANT_IDENTIFIERstill point to the right backend and tenant after the change. - Retest staff workflows: Run client, loan, savings and teller screens against the upgraded backend, even though no code changed.
- Owner: The platform team owns the version pin and deployment; application owners sign off on workflow tests.
Before starting, confirm the release notes for the chosen tag and the backend version it expects.
A fork that changes only logos, colors, text strings or favicons carries a small, predictable merge surface. The changes usually sit in theme files, translation strings and static assets. When upstream releases a new web app tag, you rebase these edits onto the new tag and check that the theme still loads. Branding changes rarely alter behavior, so the test focus is visual and string coverage on each main screen.
- Keep the diff isolated: Store branding changes in a separate directory or patch set so the rebase touches few files.
- Rebase onto the matching tag: Apply the branding patch to the web app tag that matches your target Fineract release.
- Verify strings and assets: Check that every login, navigation and form screen renders your labels and images without fallback text.
- Owner: The product or brand owner approves visual changes; the platform or front-end team carries the rebase.
Confirm whether your branding is applied at build time or through runtime configuration, because that decides whether each release needs a rebuild.
A fork with custom screens, added forms or changed approval workflows carries the highest upgrade cost. Each custom screen calls Fineract REST endpoints and depends on the field names, validation and response shapes of a particular backend version. When Fineract changes an endpoint or a product option, the custom screen can fail silently or show wrong data. Treat every custom screen as a dependency on specific API behavior that must be rebased and retested.
- Map screens to API calls: List every custom screen and the Fineract endpoints it uses, so you know what to retest after each backend change.
- Rebase custom code deliberately: Merge upstream changes into the custom files one by one, and record conflicts and decisions in the change log.
- Retest end to end: Cover each custom workflow from entry to posting, including accounting and close-of-business effects where relevant.
- Owner: The application team owns custom screens and their tests; the platform team owns the merge process and environments.
Before starting, confirm the API changes for your target version and whether a baseline API check is available for your integrations.
Questions teams ask before upgrading the Mifos X web app
Can we upgrade the Mifos X web app independently of Apache Fineract?
Usually not safely. The web app is a front end for the Fineract REST APIs, so a change in the backend can change endpoints, fields or behavior the screens depend on. You can often move the web app first in a test environment to see what breaks, but the production move should follow the backend upgrade and use a web app release tagged for the same Fineract version. Confirm the pairing for your target release against the openMF/web-app releases page before you plan the order of work.
How do we find the web app release that matches our Fineract version?
Start from the release tags on the openMF/web-app repository. Tags that carry a Fineract version suffix, such as the v1.0.0-fineract1.14 release published on December 23, 2025, indicate the backend line they were built against. Check the release notes for the Fineract version you are moving to, then confirm that the chosen tag is current and supported for that line. Record the tag in your change ticket so the front end and backend versions can be traced together.
What configuration should we check in the web app after an upgrade?
Check the environment variables the web app reads at startup. The openMF/web-app README lists FINERACT_API_URL, which must point to the correct backend, and FINERACT_PLATFORM_TENANT_IDENTIFIER, which must match a tenant identifier in the Fineract tenants table. A mismatch can produce login failures or empty screens that look like backend faults. Confirm the values in each environment, including staging, because copied settings from an older environment are a common source of confusion.
What should staff testing cover after a web app and Fineract upgrade?
Test the workflows your staff run every day, not only whether the login page loads. A practical scope covers client creation and KYC documents, loan origination and approval, repayments, savings transactions, teller and cash handling if you use it, general ledger views, reports, and end-of-day tasks. Use the same test data set before and after the change so differences are easy to see. Involve the branch and operations users who will sign off, and record each test case with the expected result.
Do custom UI changes in a forked web app need rework?
Often yes, and the effort depends on how far the fork departs from the upstream code. Changes to shared components, routing, or API calls are the most likely to conflict with a new release. Small styling or label changes may merge cleanly. Ask for an inventory of every customization, a diff against the target release, and a decision for each item: keep, rebuild on the new version, or retire. Customizations made to satisfy a previous version's behavior should be reviewed, because the reason for them may no longer apply.
What does the internal team need to provide for this work?
The team needs to know the current web app tag and any local changes, the Fineract version in use, access to the environments where the front end is deployed, and named business owners who can approve test results. It also helps to have the list of staff workflows that matter most and any configuration kept outside the code. Plan for someone who can make decisions on UI behavior and for an operator who can deploy and roll back the front end in your environment.
Can our own team upgrade the web app, and what drives the cost or time?
A team with web application and Fineract experience can often handle a standard upgrade in-house, particularly when the web app has few custom changes. The main drivers are the number of custom UI changes, the number of environments, the scope of regression testing, the availability of business testers, and whether the backend upgrade is happening at the same time. Ask any partner for a written scope that lists these items, the deliverables, and the test evidence you will receive. Pricing follows from that scope, so request a quote once the inventory is complete.
How to test staff workflows after a Fineract and web app upgrade
Organize testing around the screens staff use every day, not around the release notes, because a Fineract upgrade and a matching Mifos X web app change both the back end and the screens that call it. Build a test plan with four groups: client onboarding, loan and savings product screens, teller and accounting screens, and reports. For each group, list the steps a branch officer, teller or accountant performs in a normal day, the expected result of each step, and the person who owns the expected result. Run the plan on a staging environment restored from a copy of production data, so that existing clients, open loans, savings balances and the tenant configuration reflect real records. Record expected results before the run starts, and capture actual results with screenshots and API response identifiers so that a failure can be traced to the front end or the Fineract endpoint.
Include tenant checks in every group. Because the web app is configured with FINERACT_API_URL and FINERACT_PLATFORM_TENANT_IDENTIFIER, confirm that each tenant identifier used by staff resolves to the correct tenant after the upgrade, and that switching tenants does not show data from another tenant. Check the tenant identifier values against the Fineract tenants table, not only against the web app configuration, since a mismatch can appear as a login that succeeds with the wrong data set. Also confirm that any custom screens or labels you added still load, and that staff permissions behave as before for each role.
Hand each business owner a sign-off pack rather than a list of passed tests. The pack should contain the workflow list with expected and actual results, the defects found and their status, the custom UI changes that were tested, the tenant checks with the identifiers used, and a clear statement of any workflow that was not tested or not fixed. Ask each owner to sign off their own group, and record who signed, the build of the web app and the Fineract version under test. Agree in advance what happens to an open defect at sign-off, including whether a workflow can go live with a documented workaround, because that decision belongs to the business owner and not the test team.
What makes the front end upgrade longer or shorter
The web app upgrade is usually a small part of a Fineract release, but its effort depends on how much the front end has been changed and how many environments share it. The drivers below move the schedule in predictable directions, so they are worth scoring before a date is agreed.
Custom screens and branding
Every custom screen, form field, menu entry or theme change is code that must be rebased onto the new web app release. Heavily customized builds take longer because each change needs a merge review and a visual check. Ask how many files differ from the upstream tag and which changes are cosmetic versus functional. Light branding that lives in configuration upgrades quickly.
Tenants and environment variables
Each tenant needs its own FINERACT_PLATFORM_TENANT_IDENTIFIER value that matches the Fineract tenants table, and every build or deployment must point at the right FINERACT_API_URL. More tenants and more environments multiply the checks after each upgrade. Confirm the full variable list against the release you are moving to, not the one you are leaving.
Integrations that share tenant configuration
Any system that calls the web app, reads its configuration or relies on the same tenant identifier must be tested alongside it. Reporting jobs, single sign-on front ends and reverse proxy rules are common examples. Each one adds an owner to coordinate with and a regression path to rerun. List them before the upgrade window is set.
Number of staff workflows
Staff workflows such as client onboarding, loan approval, teller cash handling and end-of-day checks determine how much testing is required. A short list of high-volume workflows can be scripted and repeated quickly, while a long catalog of rarely used screens needs more time and more testers. Count the workflows by role and by how often each one runs in production.
Size of the test data set
Realistic test data with clients, loans, savings accounts and accounting entries lets testers see the screens behave as they do in production. A small seed set can hide pagination, formatting and performance issues that appear with larger volumes. Larger data sets take longer to load, reset and reconcile, so decide early how much history the staging copy must carry.
A parallel staging environment
A staging environment that runs the target Fineract release and the matching web app lets the team test without touching live staff work. Without one, the upgrade must happen in a shorter window with less room to roll back. Ask whether staging can be refreshed from production, how long that takes, and who owns its tenant configuration.
How DeployOpen works on this
DeployOpen plans and delivers the Mifos X web app side of a Fineract upgrade as one scoped piece of work, so the front end is matched to the backend release it will talk to. We scope the version pairing, the environment configuration, any custom UI changes and the staff test cases in writing before work starts.
How we scope
- Confirm the current Fineract release and the target web app tag that pairs with it before any change.
- Inventory FINERACT_API_URL, FINERACT_PLATFORM_TENANT_IDENTIFIER and other environment settings for each environment.
- List every custom UI change, theme or patched file and decide whether it is rebased, retested or retired.
How we build
- Build the web app from the agreed tag in a staging environment that points at a matching Fineract instance.
- Rebase custom UI changes onto the new tag and record each change as a reviewable commit.
- Run documented staff workflow tests for clients, loans, savings, accounting and reports against the upgraded pair.
How we hand over
- Deliver a version matrix showing which web app tag runs against which Fineract release in each environment.
- Document the environment variables, tenant identifier mapping and rollback steps used for the upgrade.
- Provide signed-off test results and a list of known gaps for your staff and operations team to review.
How we support
- Agree the support window, release tracking and change approval process in the written scope.
- Offer ongoing support, upgrades and continuous testing as a retainer if you want us to track future pairings.
- Confirm with your own team how production cutover timing and user communication will be handled.
