Apache Fineract JAR vs WAR on Tomcat: when each deployment model fits
The Apache Fineract documentation recommends the Spring Boot JAR, and the WAR deployed on an external Tomcat is the legacy path, so a platform team choosing a packaging model should start with the JAR unless an existing standard requires otherwise. Fineract is a headless core banking system: it exposes REST APIs and provides no user interface of its own, and the README points to the Mifos X web application as the front end in its Kubernetes example. The project recommends PostgreSQL as the database. The maintained platform is the 1.x line, because Fineract CN was deprecated in May 2023 and archived without an official release. The packaging decision matters most in two situations: when you inherit a running WAR on Tomcat, or when you plan a new environment and must decide how the application will be started, patched and moved to each new release.
Tomcat fits where your organization already runs a managed Tomcat estate with its own patching, monitoring and change process, and where that team can keep the WAR in step with each Fineract release. The JAR fits teams building container images or running on Kubernetes, where the process is the unit of deployment and configuration arrives through environment variables. Before you choose, inventory what the current deployment depends on: any plugin or JDBC driver JARs placed in the Tomcat library path, custom properties files, certificate handling and startup scripts. Each dependency must be proven again on the target release. Confirm with the documentation for your chosen version which packaging model it describes for the settings you use, and let those documented support statements drive the decision.
Plan for the cost of ownership before you commit. The README warns that a production deployment can be complex, costly and time-consuming, and that the project does not provide a comprehensive production deployment guide. The packaging design, runbooks and upgrade test cases will therefore be written by your team or by a partner. Those effort costs are largely one-time, but they recur with every quarterly release, since official releases are created at the end of each quarter and the packaging must be retested each time. When you request a quote, ask the partner to state in the written scope which packaging model they will build, who maintains the Tomcat or container layer, and how a rebuild is verified. Check the Apache Fineract platform documentation for the deployment notes that match your target version.
How the JAR and the WAR differ in runtime, startup and ownership
The Spring Boot executable JAR packages Fineract with an embedded servlet container, so the process that runs the application also serves its HTTP traffic. You start it with a Java runtime command, and the application reads its settings from environment variables and profiles at startup. The host needs a supported Java runtime and a reachable PostgreSQL server, and little else. The result is one artifact per release that moves unchanged between test and production environments.
- One process per instance: each node runs one Java process that owns its port, so scaling means starting more processes behind a load balancer.
- Embedded server settings: port, SSL and forwarded-header behavior are set through the application configuration or environment variables, so confirm the keys for your release in the documentation.
- Artifact ownership: you obtain or build the JAR, so the libraries it carries are versioned with the release you deploy.
- Container fit: the JAR maps directly onto the official container image and Kubernetes pods, where the orchestrator handles restarts and probes.
Check which configuration keys your release reads from the environment and which it reads from files, because that decides how database credentials reach the process.
The WAR is a web archive deployed into a servlet container that you install and run separately, usually by copying it into the container's deployment directory. Tomcat loads the application alongside its own configuration, JVM options and connectors. This model suits teams that already operate Tomcat as a shared platform and want Fineract to follow the same deployment process as their other Java services. Confirm the Tomcat and Java versions that your Fineract release supports before you commit to this model.
- Shared container: Tomcat may host other applications, so heap size, thread limits and connector settings affect Fineract directly.
- Context path and connectors: the application context path, TLS connector and forwarded headers are set in Tomcat configuration, which your runbook must cover alongside Fineract settings.
- Plugin placement: the locations from which extra JARs and driver files are loaded can differ from the executable JAR, so confirm the loading mechanism for your release before you plan custom plugins.
- Rebuild on release: the WAR must be rebuilt or obtained for every Fineract release and matched to a supported Tomcat major version.
Check the supported servlet container versions and the WAR build steps against the current documentation before you write the runbook.
Ownership decides who responds when Tomcat has a vulnerability, a JDK update is due or a connector setting drifts. With the executable JAR, the platform team usually owns the Java runtime and container image, and the Fineract release owns the application code. With an external Tomcat, the server is a separate asset with its own patch cycle, hardening baseline and monitoring, and someone must own it explicitly. Record that split in a responsibility matrix before go-live, including who approves changes to shared servers.
- Servlet container patching: name the team that applies Tomcat security updates, the maintenance window and the test environment used before production.
- Java runtime patching: decide whether the JDK is updated through the container image or on the host, and how each option affects rollback.
- Hardening baseline: default applications, management interfaces, server banners and connector options need a documented configuration that an auditor can read.
- Change evidence: keep records of server updates, because change management and assessment teams will ask for them.
Confirm with your security team which of these controls already apply to shared Tomcat servers and whether those controls cover a Fineract host.
Fineract's documentation describes read, write and batch instance types set through environment variables. It recommends one write instance, one batch instance and several read instances on database read replicas for high load. The packaging choice does not alter this topology, but it changes how each process is started and how the instance type is passed to it. Test each role on its own before you combine them in a cluster or on a shared server.
- Write instance: handles state-changing requests and is the only instance type that runs database migrations.
- Batch instance: runs scheduled jobs and Close of Business work, so its JVM and database connection limits need sizing separate from the API.
- Read instances: serve queries against read replicas, so their connection settings must never send writes to a replica.
- Startup order: complete schema changes on the write side before read and batch processes start, so that no process runs against an older schema.
Confirm the exact environment variable names and the replica configuration for your release in the documentation before you script either startup method.
According to the documentation, Liquibase migrations run only on write instances, and on Kubernetes they can run separately with the liquibase-only Spring profile. This matters for both packaging models, because a read or batch process that starts first must not attempt schema changes. Health checks change shape as well. The actuator endpoints are the usual input for liveness and readiness decisions, and a load balancer or orchestrator reads them through the same server that serves traffic.
- JAR migration: run the migration on a write instance with the correct profile active, and hold other roles until it completes.
- WAR migration: confirm whether migrations run as part of the WAR deployment in Tomcat and how a failed migration blocks the application context.
- Separate migration job: the liquibase-only profile lets a Kubernetes job apply schema changes once per release, which works with either packaging model.
- Health paths on Tomcat: the health path inherits the connector and context path set in Tomcat, so load balancer rules must target that exact path.
- Probe timing: slow startup on a shared container can fail probes, so set thresholds after measuring startup in your own environment.
Test a failed migration and a failed health check in a staging copy of both packaging models before you choose one.
Which packaging option fits which situation
This table compares the Spring Boot JAR, a WAR deployed on an external Tomcat, and a custom image built on the JAR across plugin support, configuration, operations and upgrades. Read each row against your plugin needs, your Tomcat standard and your read, write and batch layout. Unless you need Tomcat-managed deployment, the JAR path has the fewest moving parts to own.
| Criterion | Spring Boot JAR | WAR on external Tomcat | Custom image built on the JAR |
|---|---|---|---|
| Plugin and driver JARs | Loaded from the image or a configured loader path. Confirm the exact mechanism for your release. | Placed in Tomcat library locations. Confirm class loading and conflicts for your Fineract version. | Plugin and driver JARs are built into the image. Confirm the libs path for your release. |
| Configuration | Reads FINERACT_ environment variables, matching the official container setup. | Often split between Tomcat settings and Fineract properties. Confirm which keys apply to your build. | Same environment variable model as the official image, set by your orchestrator. |
| Container fit | Matches the published Docker and Kubernetes examples with little adaptation. | Needs a Tomcat base image and your own packaging, so it departs from the published examples. | Fits container pipelines well, with one image per Fineract release and plugin set. |
| Operations ownership | You own the image tag, configuration and the database. No separate application server layer. | You also own Tomcat versions, connector settings, patching and its security configuration. | You own the build pipeline, image scanning, rebuilds and the registry. |
| Upgrade effort | Change the image tag, then run migrations as your release process defines. | Rebuild the WAR, check Tomcat compatibility and redeploy into the server. | Rebuild on every Fineract release and retest every plugin JAR against it. |
| Read, write and batch model | Each instance type runs as its own deployment, set by environment variables. | Possible across several Tomcat instances, but you must configure each role and confirm Liquibase behavior. | Same instance model as the JAR, with each role's settings applied at build or deploy time. |
| Best fit | New container or VM deployments that need only the bundled PostgreSQL driver. | An existing Tomcat estate with a mandated application server standard and a tested migration plan. | Deployments that need extra plugins or drivers and can staff a repeatable build process. |
| Avoid when | Your standard requires Tomcat-managed deployment with no container pipeline. | You are starting a new build or need container-native rollouts and health checks. | You cannot commit to rebuilding and retesting on each release. |
Plugin support, loader paths and configuration risks
Your packaging choice decides where plugin and driver JARs go, how Tomcat loads them, and where settings live. The cards below cover the checks to run before you commit to either model. Confirm each point against the Fineract version you plan to run, since the official documentation is the authority on loader and configuration behavior.
Plugin and driver placement
Plugin JARs and JDBC drivers are added differently under each model, so an extension built for one cannot simply be copied to the other. The official Docker image ships only the PostgreSQL JDBC driver, so any other driver or plugin is your team's packaging responsibility. Confirm the documented location for each model, then test that every extension loads on a staging instance before go-live.
Tomcat classpath conflicts
An external Tomcat shares its library folders and class loading across every application it hosts. Fineract's Spring, Jackson and JDBC dependencies can clash with versions already present in that shared space, and the failure may appear only at startup or under load. Keep the Tomcat installation dedicated to Fineract, record every added JAR with its version, and recheck the dependency set on each release move.
Where configuration lives
The documentation describes environment variables that control Fineract, such as FINERACT_SERVER_SSL_ENABLED. On an external Tomcat, some settings could also sit in the container's context or server.xml, which creates a second source of truth. Confirm which settings the documentation expects in environment variables, and keep one owner per setting with the decision written down.
Tenants database connection
Fineract is multi-tenant. Requests carry a Fineract-Platform-TenantId header, and tenant connections are configured from a tenants database. Under either model, check that the tenants database settings resolve from the location your team expects, and that no Tomcat-managed data source could be picked up in their place. Test with at least two tenants before go-live, since a wrong tenant mapping can expose one client's data to another.
TLS termination on Tomcat
The Fineract documentation strongly encourages HTTPS only and documents SSL settings through environment variables such as FINERACT_SERVER_SSL_ENABLED. If Tomcat terminates TLS, the Fineract-side SSL settings and the Tomcat connector settings must agree, or the application may see the wrong scheme for incoming requests. Decide where TLS ends, configure forwarded header handling explicitly, and test the public URL end to end.
Rebuilding packaging each release
Official releases are created quarterly, at the end of each quarter, and end-of-life releases are archived. Whichever model you choose, the WAR or the JAR with your added libraries must be rebuilt, retested and redeployed for every release you adopt. Pin the Tomcat version in the same build so that a library or container change never reaches production unverified.
How to migrate an existing WAR deployment to the JAR
This sequence moves a working Tomcat WAR deployment to the Spring Boot JAR while keeping the original running until each stage is verified. It produces a tested configuration, a migrated schema and a documented rollback path.
Inventory the current WAR deployment
The platform team records the Tomcat version, the JVM options set in the startup scripts or environment, the context path the WAR is deployed under, and every plugin and JDBC driver JAR in the webapp library directory. Capture the environment variables, tenant database settings and how TLS is terminated today. Done when the inventory is written down, reviewed against a running node, and every custom JAR has a known source and version.
Map settings to the JAR configuration
Translate each Tomcat-level setting into its equivalent for the Spring Boot JAR. Tenant database connections move to environment variables, each node is assigned its read, write or batch instance type, and SSL settings such as FINERACT_SERVER_SSL_ENABLED are set deliberately. Context path and port handling usually moves to the reverse proxy. Confirm each mapping against the current platform documentation. Done when a table lists every inventory item with a target setting or an explicit decision to drop it.
Decide how custom JARs will load
Plugin and driver JARs that sat in a WAR's library directory need a planned load path in the JAR deployment, so the architect decides between a custom image and an external loader location. Check each plugin against the Fineract release you are targeting, since a plugin built for one release may not run on another. Done when every plugin has a documented load path and its compatibility with the target release is confirmed in writing.
Build and test the JAR outside production
Build the JAR from the chosen release and run it against a copy of the tenants database and each tenant database. Use separate read, write and batch instances, as you will in production, and run the scheduled jobs and API smoke tests your operators rely on today. Done when a sample tenant signs in with the Fineract-Platform-TenantId header and a representative set of read and write requests returns the same results as the WAR environment.
Run Liquibase on the write instance only
Liquibase migrations run only on write instances, so the database team starts the migration from one write node. On Kubernetes, the liquibase-only Spring profile lets the same step run as a separate job. Take a verified backup before the production run, and do not start read or batch instances against the migrated schema until it completes. Done when the changelog history in each tenant schema shows the expected changesets and a schema comparison shows no pending changes.
Cut over instances with health checks
The operations team moves production traffic in stages: the write instance first, then the batch instance, then the read instances behind the load balancer. Each stage is gated on health checks against the actuator endpoints and a tenant sign-in test. Keep a single batch instance running scheduled work so jobs are not duplicated. Done when every instance reports healthy and the job run history shows the expected runs without errors.
Keep the WAR and Tomcat for rollback
Leave the WAR, the Tomcat installation and the original configuration untouched and available until verification passes. Record the cutover time and database state so the team knows exactly what a rollback must reverse. Schema changes applied by Liquibase may not be undone by switching back to the WAR, so confirm the rollback path through a restore test from backup. Done when a rollback runbook has been rehearsed outside production and sign-off criteria are agreed before the WAR is decommissioned.
Security and operational considerations for the chosen model
Whichever packaging you choose, the same controls decide whether a Fineract deployment is safe to run. The cards below cover the items that carry across both models, and one card that only applies when Tomcat is part of your runtime.
Replace the default login
Fineract's README shows a default development login of mifos with the password password. Both the JAR and the WAR model ship with this behavior in the examples, so it must be changed before any environment is reachable from a network. Confirm that the credential is removed from every tenant, that OAuth2 or basic authentication is configured for each environment, and that the change is part of your build or deployment checklist rather than a manual step.
HTTPS only and TLS termination
The Fineract documentation strongly encourages HTTPS only and documents SSL settings through environment variables such as FINERACT_SERVER_SSL_ENABLED. Decide whether TLS terminates inside the application process, at Tomcat's connector, or at a reverse proxy or load balancer. Each choice changes which component holds certificates, how forwarded headers are trusted, and where plain HTTP traffic could still reach the service. Write the decision down for both models before cutover.
Tomcat patching and hardening
In the WAR model, Tomcat is a separate product with its own release cycle, configuration files, default applications and connectors. Each one is attack surface that the JAR model does not carry, because the embedded server ships inside the artifact you build. Ask who owns Tomcat patch intake, which default webapps and manager interfaces are removed, and how server version and configuration drift is detected across environments.
Tenant database secrets
Fineract connects to a tenants database and then to each tenant schema, so a compromised credential can expose several tenants at once. Keep these credentials out of WAR files, image layers and Tomcat context files that are checked into source control. Inject them at runtime from a secrets store or orchestrator, scope the database role to what Fineract needs, and rotate them with a tested procedure that does not require a rebuild.
Logging and job visibility
Batch and scheduler activity, including the Close of Business job, runs inside the application process in both models. Decide where Fineract and Tomcat logs are written, how long they are retained, and who can read them. Confirm that job run history is queryable, that failed or long-running jobs raise alerts, and that log locations do not change between the JAR and WAR setups in ways that break your monitoring.
Rollback ownership during cutover
A cutover between a WAR on Tomcat and a JAR service needs a named owner for the decision to roll back, and a defined point after which rollback is no longer safe because the database schema or transactions have changed. Agree who runs Liquibase migrations, who can restore the previous artifact, and how the tenants database is protected before the switch. Rehearse the rollback path in a non-production environment before go-live.
Questions teams ask before choosing or migrating
Why does the Apache Fineract documentation recommend the Spring Boot JAR?
The Fineract documentation directs deployments toward the Spring Boot executable JAR, which packages the application with its own embedded server and startup configuration. A WAR relies on an external servlet container such as Tomcat to start the application, so the container version, its configuration files and the servlet API it provides become part of what you must maintain. Fewer runtime parts means fewer places where the application and container can drift out of step. Confirm the current wording and reasoning in the platform documentation for the release you plan to run, since guidance changes between releases. Ask your team to check which packaging each release note and example manifest uses before building your own pipeline.
Can we still run Apache Fineract as a WAR on Tomcat?
Yes, a WAR can still run on a Tomcat you operate, but treat it as a legacy path and confirm it against the release you target. The supported Tomcat version, the Java runtime and the Spring Boot generation inside your release decide whether the WAR starts cleanly, and those pairings are the first thing to verify. Plugin and driver JARs must also sit where the container loads them, which differs between a WAR under Tomcat's library folders and a JAR's own loader path. Keeping the WAR is reasonable while you stabilize a release, but every upgrade then needs a second check of the container. Ask whether the project still publishes WAR artifacts for your version, and plan around the artifacts it actually produces.
What does a WAR to JAR migration involve for Fineract?
A WAR-to-JAR migration changes how the application starts, where it reads configuration and how it receives TLS and proxy settings. The work usually includes rebuilding the artifact, moving settings from setenv.sh, server.xml and container properties files into environment variables or Spring configuration, reproducing each tenant's database connection, and re-pointing health checks and the service that fronts the application. Plugin and driver JARs need a documented location in the new layout. Each instance role also needs its own start configuration, since read, write and batch instances are set by environment variables and Liquibase migrations run only on write instances. Build an inventory of these items first, because it is the basis for any written scope.
What makes a WAR to JAR migration harder or easier?
The biggest drivers are the number of plugin and custom JARs, the number of tenants and their database settings, how much configuration sits in container files instead of environment variables, and how TLS is terminated today. Each tenant adds a connection to verify, and each custom JAR needs a compatibility check against the target release. Instance topology matters too: a single combined instance is simpler than separate read, write and batch instances on read replicas, and a batch instance running the Close of Business job needs its own validation. Teams that already keep configuration in version-controlled files and run automated builds usually face less friction than teams that edit a live Tomcat by hand. Ask for any written scope to split effort by these drivers, so you can see which items are fixed and which change with your inventory.
Can an internal team migrate Fineract from WAR to JAR alone?
Yes, an internal team with Java, Spring Boot, Tomcat and PostgreSQL experience can do the migration alone, provided it has a production-like staging environment and time to test the batch job. The parts that most often need outside experience are the tenant database layout, scheduler and Close of Business behavior on the batch instance, and a rollback plan that works with the live database. Your team owns the decisions about change windows, data access and final sign-off. An outside partner adds the most value when the team lacks a specialist in one of those areas or needs documented evidence for an audit. Weigh the internal cost of staff time and delayed releases against a written, fixed scope from a partner, and request each option's assumptions in writing before deciding.
What should we send a partner before asking for a migration quote?
Send the current deployment as it actually runs, not as the intended design. Include the WAR file version, the Tomcat version and its full configuration directory, any setenv or properties files, the list of plugin and driver JARs, the tenant list with database hosts and schema names, and the instance topology with read, write and batch roles. Add the TLS arrangement, the reverse proxy or load balancer in front of Fineract, identity provider settings, and the staging and production environments you have. Describe the change window, backup and restore practice, rollback expectations and who approves production changes. List any event or integration endpoints that consume data from Fineract. A written scope built from these items lets a partner state its assumptions, exclusions and acceptance tests before work starts.
How long does testing a Fineract JAR migration take?
Testing duration depends on your environment, so measure it there instead of accepting a figure from a generic plan. The variables are how many tenants you run, how much data sits in each tenant, how long your Close of Business job takes on production-sized data, how many integrations need regression checks, and how much of your custom code has automated tests. Build a test plan with entry and exit criteria covering startup on each instance role, Liquibase behavior on the write instance, tenant connectivity, COB completion on a staging copy, authentication, TLS and the event and integration flows. Record timings from a staging run with production-like volume so the schedule reflects your data. Ask any partner to show how it derives its test schedule from those measurements.
Should we migrate to the JAR before or after a release upgrade?
Change the packaging first on the release you already run, unless that release is end of life, because changing packaging and version together makes failures harder to trace. The Fineract README states that official releases come out quarterly and that end-of-life releases are archived, so an unsupported version needs an upgrade decision regardless of packaging. If your current release is still supported, a packaging-only change gives you a known baseline to compare against and keeps rollback simple. If the release is out of support, combine the moves but add a stronger test cycle covering the database migration and each tenant. Check the upgrade notes for the target release before choosing, and confirm the release schedule in the Apache Fineract repository.
Official Apache Fineract sources to read before deciding
Before you choose between the Spring Boot JAR and the legacy WAR on an external Tomcat, read the project's own documentation and source. The Apache Fineract platform documentation is the first stop. Its deployment and configuration pages describe the packaging the project currently recommends, the environment variables that control instance types and database connections, and the SSL settings that matter if you terminate TLS at the application instead of a proxy. Check the version you intend to run, because the documentation is versioned and the current stable line is 1.15.0. Note the date the documentation was built, and confirm the page you read matches that release.
The apache/fineract repository on GitHub is the second read, and it answers questions the documentation may not. Look at the build files to see how the executable JAR is produced and whether a WAR build target still exists in the release you plan to use. Check the Docker and Kubernetes example directories for the startup command, the Spring profiles and the environment variables they set. Review the release notes and open issues for the packaging and Tomcat topics, since the README warns that a production deployment is complex and the project does not offer a comprehensive production guide. Record what you confirm in writing, with the release tag, so your decision and your upgrade plan refer to the same artifact.
How DeployOpen scopes and delivers Fineract packaging work
DeployOpen plans, implements, hardens and documents self-hosted open-source platforms inside your own infrastructure, including the packaging decision between the Spring Boot JAR and an external Tomcat WAR for Apache Fineract. Each engagement starts from a written scope that records which deployment form your plugins, drivers and operating standards require.
How we scope
- Inventory every plugin, driver and custom module that your Fineract build must load before choosing a packaging form.
- Record the application server, JVM, operating system and CI tooling your organization already runs and must support.
- Agree the written scope, deliverables and timeline in writing before any packaging work starts, with fixed scope as the default.
How we build
- Build the chosen artifact from the matching Fineract release and confirm its startup, configuration and external library loading.
- Configure tenant database connections, HTTPS settings and environment variables in a repeatable, version-controlled form.
- Test a WAR-to-JAR migration in a non-production environment with the same tenant data and rollback steps prepared.
How we hand over
- Deliver build scripts, configuration references and a runbook covering upgrades, rollback and the artifact's supported runtime.
- Walk your platform and operations teams through the deployment steps, startup checks and troubleshooting of library loading.
- Document every decision on packaging form, including the reasons, so future upgrades and audits can trace them.
How we support
- Review each new Fineract release for packaging changes before your upgrade is scheduled, and report what your team must change.
- Ongoing support, upgrades and continuous testing are available as a retainer, scoped in writing separately from the build.
- Confirm with your own environment and the project documentation any runtime or server version the chosen artifact requires.
