Running Apache Fineract on a private or air-gapped network

Running Apache Fineract on a private or air-gapped network: when teams need it

A regulated institution that wants its core banking system reachable only from the corporate network, or not connected to the internet at all, can usually run Apache Fineract that way. Fineract is a headless application: it exposes REST APIs and does not ship its own user interface, so the back end can sit on a private subnet and be reached through VPN-only access with a short list of open ports. The Mifos X web application is the front end the project's Kubernetes example uses, and it is also deployed inside the same private boundary. Because Fineract is self-hosted, every component, from the PostgreSQL database to the container images, lives in infrastructure you control, which is what makes isolation possible in the first place.

Air-gapped back-office accounting is the right pattern when the core system must hold no live connection to external payment rails, notification services or vendor clouds, and when the institution accepts that some workflows move by controlled file or manual transfer. In that model, Fineract runs its loan and savings portfolios and real-time accounting inside the boundary, and an approved process carries images, packages and reports across it. Every package carried across the boundary needs integrity verification, and the process for doing so should be written down before go-live. Confirm with your own assessors which isolation pattern they expect for your system's impact level.

Plan for a heavier build than a connected deployment. The Fineract 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. Mirroring images, rebuilding the Kubernetes or container layer without internet pulls, setting up internal logging and backups, and testing restores all fall to your team or your implementation partner, so the isolation design should be settled before the build starts.

Which isolation pattern fits which operating model

This table compares three ways to isolate a Fineract deployment: VPN-only access with limited ports, a restricted-egress network that pulls from a mirror, and a fully air-gapped back office. Read each column as one operating model, then check the access path, what breaks, and who approves and maintains what. The main takeaway is that the more isolated the pattern, the more of the update, patching and integration work moves to a controlled transfer process that your team must staff and evidence.

Dimension	VPN-only with limited ports	Restricted egress with mirror	Fully air-gapped back office
Access path	Staff and admins reach Fineract APIs and the web front end only through a VPN into the private network, with a few allowed ports	Fineract runs in a private network with no inbound internet route; outbound traffic goes only to an internal registry, package mirror and approved endpoints	No network route to the internet or to external services; data and software enter and leave through logged, controlled media transfers
What breaks	Vendor support sessions, remote consultants and any SaaS payment or notification callbacks that need inbound access	Image pulls and dependency installs fail until the mirror is current; external payment switches and SMS or email providers need explicit egress rules	Automatic updates, live payment and notification integrations, external identity providers, and any tool that checks a public service at runtime
Who maintains images and packages	Your platform team keeps images and dependencies current through the normal pipeline, with access limited to the private network	Your platform team mirrors approved images and packages into an internal registry and repository, and records each sync	Your team builds or verifies every artifact outside the boundary, then carries it across; the same team owns the offline repository and its contents
Who approves transfers	Usually no per-transfer approval; access approvals for VPN accounts and firewall rules apply	Change control approves each mirror sync and each new egress destination	Named approvers from security and operations sign off each media transfer, with checksum and signature verification recorded before import
Typical evidence an assessor expects	VPN and firewall rule sets, MFA records for remote access, and admin access logs	Mirror sync logs, allowed egress lists, and records of software integrity checks on mirrored artifacts	Transfer logs, media chain of custody, integrity verification records, and a documented procedure for each import
Where it usually fails	Shared VPN accounts, broad port ranges opened for convenience, and admin ports left reachable from the VPN subnet	Mirror falls behind the Fineract release cycle, or egress rules are widened permanently to fix one failed pull	Transfers are batched too rarely, so security patches wait for the next media cycle, or integrity checks are skipped under schedule pressure
Best fit	Organizations that need internet-facing services removed but can keep normal update and integration paths	Organizations that need controlled updates and some external connectivity, with a central team managing the mirror	Back-office accounting or core processing that must have no network path out, with planned, slow release windows

What you lose when Fineract is offline

An air-gapped Fineract instance keeps its ledger, loans and savings running, but anything that depends on an outside party stops or needs a manual path. Each card below names one dependency, the workaround you can build inside the boundary, and the decision the bank must make before go-live.

Payment switches and rails

Disbursements and repayments that move money through an external payment switch or clearing network cannot complete from an isolated segment. Fineract still records the transaction, so the gap is between its ledger and the settlement file. Decide whether payments run through a file-based exchange, a dedicated transfer host with a controlled egress path, or a manual process with dual approval. Ask the switch provider which connection modes it supports before assuming any of them.

SMS and email notifications

Reminders, due-date alerts and statements sent to customers depend on outbound messaging providers that sit outside your network. Without them, customers miss repayment dates and delinquency rises for reasons unrelated to credit risk. Decide whether notifications are queued inside a segment that relays through an approved gateway, or whether outreach moves to branch and call-center scripts. Confirm which channels your teams can staff manually and how the messages are logged for audit.

Third-party identity providers

If staff or customers sign in through a cloud identity provider, that login path fails when the provider is unreachable from the isolated network. Staff who need access may be locked out during an incident. Decide whether authentication is handled by an identity service you run inside the boundary, and how break-glass accounts are created, stored and reviewed. Confirm that Fineract's configured authentication methods work without the external provider.

External document and KYC checks

Identity verification, sanctions screening and credit bureau lookups usually run as hosted services. Offline, onboarding either stops or proceeds on documents that have not been checked. Decide which checks must happen before a client record is activated, whether the bank keeps an approved offline copy of reference lists, and how exceptions are recorded. Confirm with your compliance team which evidence an examiner would expect for each check performed outside the system.

Vendor-hosted monitoring and updates

Hosted monitoring, error tracking and vulnerability feeds send data out of the network and receive alerts or patches in return. Without them, you lose external visibility and automatic signature or package updates. Decide which telemetry stays inside the boundary, which self-hosted monitoring stack replaces the hosted service, and how updates arrive through a reviewed transfer process. Confirm the integrity checks you will apply to every package carried across the boundary.

How to build the isolated Fineract environment

This sequence takes an empty set of servers inside a private boundary to a running Fineract tenant with migrated schemas, read and batch instances, TLS and changed credentials. Each step ends with a check you can record as evidence before the next step begins.

Define the perimeter and allowed ports
The network team writes down every zone, host and port the platform needs: VPN or bastion entry points, the load balancer, the Fineract write, read and batch instances, the PostgreSQL primary and replicas, the container registry and the package mirror. Everything else is denied by default, and no route to the public internet is allowed from the application zone. Done is a reviewed firewall matrix that the security team has signed off, with each rule tied to a named service. Confirm the exact ports with your own deployment files, since the project does not publish a complete production port guide.
Mirror images and dependencies into the boundary
Build or pull the Fineract image from the official source, then copy it into a private registry together with every base image, the PostgreSQL JDBC driver, the Mifos web application if you use it, and any OS or Maven artifacts your build needs. Record the image digests and checksums so the copies can be compared with the originals before transfer. Where Kubernetes is used, run kubeadm config images list and kubeadm config images pull on a connected staging host, then point kubeadm init at the private registry with the --image-repository flag. Done is a registry listing with digests that match the staging records, and a test pull from a host with no internet route.
Prepare PostgreSQL inside the boundary
The database team installs PostgreSQL, which the project recommends over MariaDB and MySQL, and creates the tenants database plus the application roles with the least privileges the deployment needs. Set the server to UTC and provision read replicas if the read instances will use them. Restrict access to the database subnet so only the write, read and batch instances can connect. Done is a successful login from each application host using its own credentials, and a query against the tenants database that returns the expected tenant list, which is empty until migration runs.
Run the Liquibase migration on a write instance
Start a single write instance with the database and tenant settings supplied through environment variables, and let it apply the Liquibase migrations. The documentation states migrations run only on write instances, so do not start read or batch instances against an unmigrated schema. On Kubernetes, the liquibase-only Spring profile can run this as a separate job. Done is a clean migration log with no failed changesets, and a database check showing the tenant schemas exist.
Bring up read and batch instances
After the write instance has finished migrating, start the batch instance, which runs the scheduled and Close of Business work, and then the read instances, which should point at read replicas where you have them. Set the instance type through the environment variables the documentation describes, and keep one write and one batch instance. Done is each instance reporting healthy on its health endpoint, and the logs showing the scheduler starting on the batch instance only, not on the read instances.
Set TLS through the documented SSL variables
Enable HTTPS with the SSL settings the documentation exposes, such as FINERACT_SERVER_SSL_ENABLED, and supply a certificate issued by your internal certificate authority in place of the built-in self-signed one. If a reverse proxy or load balancer terminates TLS instead, confirm forwarded header handling with your own configuration before going live. Done is a successful handshake from a VPN client using the internal CA chain, and a failed connection from any client that does not trust that chain.
Change the default mifos login
Replace the development account named mifos and its default password before any user or integration can reach the API. Create named operator accounts or connect OAuth2 identity, assign roles to match your maker and checker model, and store service credentials in your secrets manager inside the boundary. Done is a test showing the default login is rejected on every instance and a role-scoped account can perform only its assigned actions.
Verify each stage and retain evidence
Run a final acceptance check that covers the firewall matrix, a connection attempt from outside the VPN, a registry pull from an isolated host, the migration result, instance health, TLS handshake results and the credential change. Keep the outputs, digests and change records together so the audit trail shows what was built, from which artifacts and when each control was tested. Done is a signed acceptance record that the platform owner and security team both accept before any business data is loaded.

How software and data cross an isolated boundary

Software that enters an isolated network includes container images, Spring Boot JARs, plugin and JDBC driver files, operating system packages and vendor patches. Each item should be obtained from a source you can name, checked against a published checksum or signature where the publisher provides one, and scanned for known vulnerabilities before it reaches the enclave. Fineract's own release artifacts come from the Apache project, so record the exact tag or version you pulled, not just the image name you referenced.

Source capture: Record where each artifact came from, the exact version, and the person who downloaded it.
Integrity checks: Verify checksums or signatures against the publisher's published values before the file is staged.
Vulnerability scanning: Scan images and packages on the outside network and again after transfer, using a scanner that can work from an offline vulnerability database.
Staging registry: Import images into a private registry only after review, and reference them by digest in deployment manifests.
Dependency review: Confirm that plugin JARs and driver files are the ones approved for Fineract, since anything dropped into the libs path runs inside the banking application.

Confirm with your security team which scanner, signature method and offline feed they accept, and whether the transfer medium itself is logged and controlled.

Security and operational controls for restricted networks

When Fineract runs without internet exposure, the perimeter is built from access paths, authentication and visibility rather than from public-facing controls. The cards below cover the Fineract settings, network rules and logging decisions that have to be made together, and what to verify before go-live.

Remove the development login

The Fineract README ships a default development login (mifos with a matching password) for OAuth2 and basic authentication. On an isolated network it is easy to assume the exposure is small, but any account left in place becomes a standing path for anyone with network access. Confirm that the default user is disabled or replaced, that service accounts are separate from named staff accounts, and that credentials are supplied from your secrets store rather than from compose files or manifests.

Enforce HTTPS only

The Fineract documentation strongly encourages HTTPS only and configures SSL through environment variables such as FINERACT_SERVER_SSL_ENABLED. Set this explicitly in every environment, including the internal ones, and reject plain HTTP at the listener or the reverse proxy. Decide where certificates come from, since an internal certificate authority is usually the only option without internet access, and confirm that every client, batch job and integration trusts that authority.

Restrict administrative APIs to named networks

Administrative and back-office endpoints should not be reachable from the whole VPN pool. Place them behind a proxy or internal load balancer that allows only the subnets of named operations teams, and keep read and batch instances off the path that customer-facing tools use. Test the rules from both an allowed and a denied address, and record which tenant and role combinations can reach which paths.

MFA for remote access

NERC CIP-005-7 requires that Interactive Remote Access to high and medium impact BES Cyber Systems pass through an Intermediate System with encryption and multi-factor authentication. Fineract is not a BES Cyber System by default, so apply this only where your regulator or your classification says it applies. Where it does, confirm that the VPN or jump host enforces MFA for every remote session and that the path to Fineract cannot be reached without it.

Monitor and end vendor sessions

CIP-005-7 also expects methods to detect and disable active vendor remote access sessions. Apply the same principle to any vendor or partner who supports Fineract: give them time-limited access, log their sessions, and keep a documented procedure to terminate a session at the VPN or proxy. Ask your support provider to show how a session is ended and how the action is recorded.

Forward logs without internet egress

Application, proxy and VPN logs have to leave the restricted network for review, but the collector cannot call a public SaaS endpoint. Choose a log destination that runs inside the same boundary, such as a self-hosted log platform, and send logs over an approved internal path. Confirm which Fineract log categories contain personal data, set retention on the receiving side, and test that a restored or rotated log set can still be searched.

How to patch and upgrade Fineract without internet access

How often does Apache Fineract publish new releases?

The Fineract README states that official releases are created quarterly, at the end of each quarter, following the ASF release policy. That cadence means a disconnected site should plan for four candidate releases a year, not one. Not every quarterly release needs to be adopted. The decision is which release line you stay on and how far behind the current stable release you are willing to run. Confirm the current stable version on the project website before setting your calendar, since versions change each quarter.

How do we stage a new Fineract image and its dependencies offline?

Pull the new Fineract image, the matching database driver and any sidecar or front-end images on a connected build host, then scan and verify each artifact before it crosses the boundary. Push the images to your internal registry and record their digests. Mirror the Java and OS packages your build depends on in the same batch so a rebuild inside the perimeter does not need outside access. Keep the image tag, digest and checksum in your change record. Confirm with your own registry and scanning tooling which mirror features it supports.

Should we test a new Fineract release on a non-production tenant first?

Yes. Deploy the new release to a staging environment that uses a copy of production data, and run the upgrade against a non-production tenant before touching live tenants. Fineract is multi-tenant, so test each tenant schema you run, not only the default one. Compare key outputs such as Close of Business results, loan schedules and accounting journals against the current release. Record the test evidence, because the perimeter's change process will ask for it. Plan how long the test cycle takes with your own team; this depends on tenant count and data volume.

What does the Liquibase step involve during an upgrade?

Liquibase applies database schema changes, and according to the Fineract documentation those migrations run only on write instances. On Kubernetes, you can run them as a separate job with the liquibase-only Spring profile, which keeps schema changes out of the normal application rollout. Take a verified database backup before the step, because schema changes are not simply reversed. Run the migration in staging first, then in production during the approved change window. Keep the read and batch instances off the new version until the write-side migration has finished.

What happens when a Fineract release reaches end of life?

The README states that end-of-life releases are archived. An archived release no longer receives the project's fixes, so a site that stays on it accumulates unpatched exposure. Track the support status of your release line against the project's published policy and plan the next move before the line is archived. Because you cannot pull patches on demand, the offline mirror must bring in each supported release in time. Confirm the current support window with the project documentation rather than assuming one.

How do we fit Fineract upgrades into our change control?

Build the upgrade calendar around your perimeter's change process, not around the release date. Regulated sites often need a change advisory board, a security sign-off on each imported artifact and a documented rollback plan. Ask your change board how many days of lead time it requires and which windows it approves, then work backward from the quarterly releases. Some quarters you may skip a release, and that decision should be recorded and reviewed. Expect the process to take longer than the technical work.

Can our own team handle offline Fineract upgrades, and what would a partner add?

A team with Linux, container, PostgreSQL and Fineract experience can run the process in-house, and that is often the lower-cost route for a stable deployment. The work recurs every quarter, so the cost is ongoing staff time, not a one-off project. A partner can be engaged for a fixed-scope upgrade or a retainer covering releases, mirror maintenance and test cycles. DeployOpen plans, implements, upgrades, documents and supports self-hosted platforms inside the client's own infrastructure, including air-gapped networks. Ask for a written scope and quote before work starts.

Limits to confirm in your environment

A private or air-gapped Fineract deployment fails less often on the platform itself than on assumptions about what the surrounding systems need from the internet. The cards below list the checks that connect the front end, identity, events, backups and audit evidence to the boundary you actually operate.

Front end and identity offline behavior

Fineract is headless and ships no user interface, so the Mifos web application or another front end is a separate component you must confirm. Check whether its build assets, fonts, map tiles and login flow load from inside the boundary. Confirm that your identity provider works with OAuth2 or HTTP basic authentication without calling external discovery endpoints, certificate revocation services or hosted login pages. Test sign-in with the network cut off, not just with the firewall rules you intended to write.

Modules with outbound calls

Some Fineract modules and configured integrations call external services, such as payment switches, notification gateways, exchange rate or holiday feeds and document storage endpoints. Build an inventory of every module and global setting in use, then mark each one that opens an outbound connection. Anything that depends on an external call needs a documented offline alternative or a deliberate exclusion from the go-live scope.

Event publishing stays internal

Business event publishing to ActiveMQ, other JMS brokers or Apache Kafka is disabled by default, so enabling it is a deliberate design decision. Confirm that the broker, its topics and any consumer applications sit inside the same boundary as Fineract. Check that no consumer replicates events to a cloud service or external analytics tool. Also confirm how events are retained and who can read them, because event payloads often carry client identifiers.

Tenant database backup inside the boundary

Each tenant has its own database, and the tenants database holds the connection details for all of them, so backups must cover both. Confirm where dumps or archive copies are written, which storage platform holds them, and how they are encrypted and moved between sites without leaving the network. Restore tests should run on an isolated host inside the boundary, and you should confirm that the backup tooling itself does not need internet access to function.

Regulator and auditor evidence needs

Confirm which regulator, examiner or external auditor will review the deployment, and ask them what evidence they expect from an isolated system. Common requests include access logs, change records for container images, proof of software integrity checks for carried-in packages, and records of who can reach administrative paths over the VPN. Some frameworks also require documented remote access controls for systems that support critical infrastructure. Agree the evidence list in writing before you finalize the network design, since the boundary decides what can be collected.

Package and image transfer controls

Every container image, JAR, driver and operating system package that crosses into the isolated network needs a recorded source, a version and a verification step. Confirm which signatures or checksums your mirror publishes and who approves each transfer. Also confirm that Fineract image tags map to the release you tested, because upgrades inside an air-gap depend on a repeatable transfer process rather than on pulling the latest tag.

Questions teams ask before running Fineract air-gapped

Can an internal team run Apache Fineract air-gapped without outside help?

Yes, if the team already owns the skills, but the work spans more disciplines than a Fineract build alone. An internal team needs people who can run PostgreSQL, Kubernetes or a VM platform, build and mirror container images, operate a patch transfer process, and keep Fineract's configuration correct across releases. Fineract's own documentation says a production deployment can be complex and time-consuming and that the project does not provide a comprehensive production deployment guide, so most teams either staff that depth in-house or buy it. Ask whether the team has done an offline upgrade before, because the first one is where gaps appear.

What drives the cost of an air-gapped Fineract deployment?

Cost follows the number of boundary crossings and approvals, not the Fineract software, which is licensed under Apache-2.0. The main cost components are:

Network design: zone layout, VPN concentrators, firewall rules and jump hosts.
Mirroring: an internal registry, package repositories and a repeatable import path for every Fineract release and base image.
Change control: evidence for each transfer, test runs in a staging enclave and sign-off from security and business owners.
Staff time: network, DBA, security and application engineers working in parallel.

Some costs are one-time, such as the initial build. Others recur with each quarterly Fineract release and each security patch. Ask any partner to split the quote along these lines.

What does the bank need to provide for this work?

The bank needs named people from several teams before the first design session. Network teams own the perimeter, VPN and port allow-lists. DBAs own the PostgreSQL platform, backups and the tenants database. Security approvers own the transfer process, vulnerability review and access decisions. Business owners confirm which offline functions must work on day one and which can wait. Platform or cloud owners provide the hosts or clusters. If one of these roles is missing, the design usually stalls at the first boundary decision, so confirm each name and their decision rights early.

How long does an air-gapped Fineract project take?

Duration depends mostly on the perimeter, the number of approval gates and how quickly the bank can review transfers, not on the Fineract build itself. A simple design with one enclave and a single approval path moves faster than one with several network zones, vendor access rules and separate evidence reviews. Ask for the timeline to be tied to named milestones: network design sign-off, first mirrored image import, staging build, security review and production cutover. Any firm duration should appear in the written scope, since DeployOpen agrees scope, deliverables and timelines before work starts.

Can Apache Fineract run fully offline with no internet access?

Fineract itself can run without internet access once its container images, JDBC driver, database and dependencies are available inside the enclave. Its core services are headless REST APIs backed by PostgreSQL, so accounting, client records, loan and savings processing and Close of Business jobs do not depend on a public service. What is lost offline is everything that calls outside: payment switches, SMS and email notifications, webhooks to external brokers, OAuth2 providers hosted elsewhere and any hosted document storage. Confirm each of those integrations with the owners before you design the boundary, and confirm the exact behavior of your chosen front end and identity provider offline with their vendors.

How should we keep Fineract images and dependencies current without internet access?

Mirror every artifact on a scheduled cycle and verify it before it crosses the boundary. Include the Fineract image for each tag you plan to run, the base images, the PostgreSQL driver, Java libraries, operating system packages and the front end. Record a checksum or signature for each item and keep the transfer log as evidence. This matters for supply chain control: NERC CIP-013-2 requires procurement processes to address verification of software integrity and authenticity of vendor software and patches, and similar expectations appear in many bank third-party frameworks. Confirm with your security approvers which verification method they accept before the first import.

Does an air-gapped deployment change how we control access and remote support?

Yes. Access moves through a controlled entry point such as VPN-only access with a small set of allowed ports, and vendor sessions must be time-limited and logged. If your bank is in the energy sector or follows similar rules, NERC CIP-005-7 requires interactive remote access to pass through an intermediate system with encryption and multi-factor authentication, and it expects methods to detect and disable active vendor sessions. Even outside that sector, plan for multi-factor access, separate admin and operator roles, and a documented process for emergency access to the database and the tenants database. Confirm the exact requirements with your compliance team, since they depend on your regulator and impact classification.

How DeployOpen scopes and delivers an isolated Fineract deployment

DeployOpen is a Chainscore Labs company that plans, implements, hardens, backs up and documents self-hosted open-source platforms inside the client's own infrastructure, which for an isolated Fineract deployment means the client's data center, private cloud or air-gapped network. The work is agreed before any build starts. Most engagements are fixed-scope, so the written scope names the networks, the access paths, the components to mirror, the Fineract instance types and the handover documents. A quote follows directly from that written scope, which is why the questions below should be answered in the scoping conversation rather than during delivery: which VPN gateways and jump hosts are approved, who holds the offline accounting workstation, how packages are approved for transfer across the boundary, and which upstream release is the baseline.

Delivery usually moves through the same sequence described in this topic: confirm the network boundary, build and verify the offline image and dependency mirror, deploy the Fineract write, batch and read instances, then test the restricted access paths and the back-office accounting process. Each step produces artifacts such as the mirror manifest, firewall rule sets, hardening results and runbooks. DeployOpen prepares systems, controls and evidence for compliance assessments, so an assessor can review them, but DeployOpen does not issue audit reports, attestations or certifications. Those come from independent auditors or certification bodies. Ask in the proposal which evidence items are in scope and who owns each one after handover.

Ongoing work after go-live is also scoped in writing. Support, upgrades to later Fineract releases, mirror refreshes and repeated testing of the VPN-only paths can be arranged as a retainer, with the frequency and response expectations stated in the agreement. Ask whether the retainer covers the offline update process, since each new image or library must cross the isolated boundary again and be checked before it is loaded. Before signing, confirm what is one-time (design, build, initial testing, documentation) and what recurs (retainer, licensing for any mirrored third-party products, and your own staff time for approvals), and ask for each in the quote so the two sides compare the same scope.

Running Apache Fineract on a private or air-gapped network