ERPNext high availability: architecture and build guide

What ERPNext high availability requires before you start

For a finance or operations team, an ERPNext outage during month-end close or a stock count is a business problem, not just an IT ticket. High availability means removing every single point of failure across the web tier, background jobs, the scheduler, the database and Redis, so that one failed component does not stop users from posting, closing periods or counting stock. A second web server is one part of that work, and on its own it gives you very little protection. The reason it is harder than it looks is that ERPNext runs on the Frappe Framework, which keeps shared state in MariaDB and Redis. Sessions, cache, realtime events and the job queue all depend on those services. The scheduler triggers recurring tasks, and background workers execute queued jobs such as report generation, email and long-running posting tasks, separately from the requests users make in the browser. If a worker dies midway through a job, the outcome depends on how that job was written and how your queue is configured. Ask your implementation team to show you exactly what happens to in-flight jobs when a node fails.

Before you choose an architecture, map each component to a location and an owner. List where the web processes, Socket.io, Nginx, workers, the scheduler, MariaDB and Redis will run, and whether each can be lost without taking the others with it. Decide whether MariaDB will use replication with a documented failover procedure, and who performs that failover at 2 a.m. during a close. Decide whether Redis will be shared across nodes or placed per node, and confirm how uploaded and private files are stored so every web node serves the same content. Each of these decisions changes the hardware, the licensing of supporting tools, and the skills your team needs.

Version choice also belongs in this first stage. According to Frappe's supported versions page, ERPNext and Frappe Framework version 14 reached end of life on January 31, 2026, version 15 is planned to be supported until the end of 2027, and version 16 until the end of 2029. Both supported major versions receive frequent minor releases, so an availability design must include a rehearsed process for applying updates with bench update and bench migrate without taking the whole system down. Confirm the support window for your chosen version before you design around it, and note that Frappe's supported versions policy ties warranty coverage to a listed version and a matching Frappe Cloud support plan.

Custom apps and scripts add another dependency. Server Scripts are disabled by default from version 15 onward and must be enabled deliberately, so check whether your deployment depends on them and whether any custom app assumes a single process or local file storage. Any code that writes to local disk, holds in-memory state or runs only on one node will break under failover. Ask your team to inventory custom apps and test them against a multi-node staging environment before production work begins.

Finally, set the availability goal in writing before anyone prices the work. This page does not claim an uptime figure, because the right target depends on your close calendar, your tolerance for lost jobs and the budget you can justify. Ask any implementation partner for a quote that separates one-time work (architecture, replication setup, failover runbooks, testing) from recurring costs (hosting for redundant nodes, database and Redis operations, monitoring, patching and internal admin time). A fixed-scope quote should state which components are covered and how each failover scenario will be tested.

Which ERPNext components need separating and replicating

An ERPNext deployment is a set of cooperating processes rather than one application, and each process fails, scales and recovers differently. The cards below list the components that the frappe_docker services list separates, so you can decide which ones run on their own hosts, which ones can be replicated, and which ones hold the data you must protect.

Web processes behind Nginx

Gunicorn serves ERPNext web requests, and Nginx sits in front to handle TLS and routing to the site. The web tier holds no business data itself, so it is the simplest layer to run as several instances behind a load balancer. Check that sessions and uploads do not depend on one instance's local disk, and confirm how your chosen deployment routes requests to each site.

Socket.io realtime service

The Socket.io service carries realtime updates to open browser sessions, such as notifications and live document changes. It is a separate service in the frappe_docker reference set, so it can fail or be restarted without stopping the web tier. Confirm that your load balancer supports the connection behavior it needs, and test that users reconnect cleanly after a restart.

Background workers

Background workers run queued jobs such as report generation, email sending, and long imports. They hold no authoritative state of their own, but they read and write the same database and queues as the web tier. Scale them by queue type and watch for jobs that keep failing, because a backlog can look like an outage to users who never see the worker layer.

Scheduler

The scheduler triggers periodic jobs such as recurring tasks, reminders and scheduled reports. Only one scheduler should be active for a given site, since duplicate scheduling can send the same email or run the same job twice. Confirm your deployment's approach to running a single active scheduler before you add any second host.

MariaDB database

MariaDB holds all transactional ERPNext data, including ledgers, stock and documents, so it is the stateful component that drives most of your recovery design. Plan for replication to a standby, point-in-time recovery, and tested restores, and confirm with your ERPNext version which replication topology your team can support and operate.

Redis for cache and queues

Redis serves two roles in ERPNext: a cache and the queue backend for background jobs. Losing cache is usually recoverable, but losing queued jobs can silently skip work, so decide whether Redis needs persistence and whether cache and queues should share an instance. Check the frappe_docker Redis services and your own failover approach before going live.

Private and public file storage

ERPNext stores attachments and generated files as private and public files on the site's file system, and these files are not in the database. A failover that restores the database without matching files leaves broken attachments, so the file store must be shared, replicated or backed up alongside the database. Confirm where each file type lives in your setup.

Bench directory and site configuration

The bench directory holds installed apps, site configuration and the site's private keys and settings. Every web, worker and scheduler instance must run the same app versions and matching configuration, so treat the bench as a versioned artifact. Confirm how you keep bench contents identical across hosts and how you back up the configuration with the database.

Choosing a high availability design for ERPNext

This table compares five ERPNext designs, from one bench on a single server to a container deployment, by when each fits and the operating work it adds. Read each row as a step up in availability, which also brings more components to patch, monitor and fail over. The main takeaway is that a second web node or a database replica helps little on its own unless shared files, background jobs and a tested failover runbook are covered too.

Design	When it fits	Operational cost it adds
Single bench on one server with scheduled backups	Small user groups that can accept a restore window after a server failure	Restore time depends on regular restore tests; patching takes the system offline; one host to monitor
Web and worker split on one site with a single MariaDB	Growing load from long jobs such as reports or imports slowing down the user interface	Two application hosts to patch in step; Redis and queue health to watch; the database is still a single point of failure
Replicated MariaDB with a hot standby	Data loss and database outage are the main risks the business needs to limit	Replication lag to monitor; a failover runbook that is rehearsed; DBA skills; application settings must follow the new primary
Multiple web nodes behind a load balancer with shared storage	Many concurrent users, or a single web server that is itself a single point of failure	Shared file storage for site files; session handling across nodes; configuration drift between nodes; each node patched separately
Container deployment with frappe_docker	Teams already running a container platform that want repeatable builds and rollbacks	Rebuilding images for each update; registry and volume management; orchestration skills; the single-file demo setup is for short-lived evaluation only

How to build an ERPNext high availability setup step by step

This sequence moves a single bench toward a setup where the database, cache, file storage, web tier and background work can each be maintained or replaced with less impact on users. Each step ends with a check, so the layer below is confirmed stable before the next one changes.

Confirm ERPNext and Frappe versions and support status
Your team or implementation partner records the exact ERPNext and Frappe Framework versions in use, every custom app, and the dependencies each one needs. Compare these against Frappe's supported versions page, which lists version 14 as end of life from January 31, 2026, version 15 as supported until the end of 2027, and version 16 until the end of 2029. If you want Frappe warranty coverage, confirm you are on a listed version and hold a matching Frappe Cloud support plan. Done when a version inventory with a support end date for each component is signed off.
Move MariaDB and Redis onto dedicated hosts
The infrastructure team provisions separate hosts for MariaDB and Redis, sized and secured for the load they will carry, and points the site configuration at them instead of local services. Restrict network access so only web, worker and scheduler nodes can reach these ports. Confirm sizing with your database administrator and implementation partner, since the right values depend on your own usage. Done when the site loads, a user can log in, and a saved document appears in the database on the new host.
Set up database replication and confirm replica health
The database administrator configures MariaDB replication from the primary to at least one replica on a separate host. Review the replication user, binary log settings and network path against your recovery design before go live, and keep backups running from a location you control. Check that the replica reports it has caught up with the primary, then save a test record on the primary and confirm it appears on the replica. Done when replication stays stable under normal business load and replica lag is visible in your monitoring.
Move shared file storage to a common location
ERPNext stores uploaded attachments and generated files in the site files directory, so every web and worker node must read and write the same location. Move that storage to a network file system or object storage your platform team supports, and mount it on each node at the same path. Confirm the storage choice and its file locking behavior with your implementation partner before cutover. Check by uploading an attachment through one web node and downloading it through another. Done when both nodes show the same file and a PDF generated by a worker is readable from the web tier.
Split web, worker and scheduler roles
Run the web processes, background workers and scheduler as separate services, each on its own node or container, all using the same codebase and site configuration. If you use frappe_docker, these map to separate services for workers and the scheduler. Keep exactly one scheduler active across the cluster so scheduled jobs are not executed twice, and confirm that the worker queues your customizations depend on are served. Check that a background job queued from the user interface completes on a worker node, and that a scheduled job runs once in its expected window. Done when logs show a single execution for each scheduled job.
Configure load balancer with health checks and TLS
Place a load balancer in front of the web nodes and terminate TLS there or at the Nginx layer, with certificates managed under your standard process. Configure a health check against a path the web tier serves, and remove any node that fails it from the pool. Set the check interval and failure thresholds with your platform team based on your load balancer's documentation rather than defaults. Check that HTTPS works end to end, that stopping one web node drops it from rotation, and that a logged-in user keeps their session after requests move to another node. Done when all three checks pass.
Rehearse a failover in a staging environment
Write a runbook covering promotion of the replica, repointing the site configuration, restoring the file storage mount, and returning web and worker nodes to rotation. Run it in staging against a copy of production data, with each role named in advance. Create a known set of test records before the drill, then compare them with the restored data afterward. Record how long each step takes and measure it against the recovery target your business has agreed. Done when a test transaction posts successfully on the promoted database, the drill completes without undocumented manual fixes, and the runbook is updated with anything missed.

How the high availability design changes by deployment model

With bench on virtual machines, your team controls every component: web workers, background workers, the scheduler, Socket.io, Redis, MariaDB and the reverse proxy. High availability means placing each tier across more than one host and owning every failover step, including the ones a managed platform would normally handle.

Database: choose and configure MariaDB replication or a managed database service, and decide how application servers reconnect after a primary changes.
Redis and queues: plan Redis so a failed node does not silently lose queued background jobs, and test how jobs resume after failover.
Shared files: decide where site files and assets live so every web and worker node reads the same data.
Load balancing: place a proxy in front of web nodes and define health checks that remove a failed node from rotation.
Backups: schedule bench backups to storage outside the failed host and rehearse restores.

Confirm the failover runbook owner, and rehearse loss of the primary database in staging before go-live.

What drives high availability effort and cost in ERPNext

This table lists the factors that change how much work a high availability ERPNext setup takes to design, build and run, with the direction each factor pushes effort and a practical way to keep it manageable. Read it before asking for a quote, because the drivers you can control are the ones that move cost most. None of the rows carries a price or duration, since those depend on your written scope and environment.

Driver	Why it changes effort	How to keep it down
Number of sites and companies	Each site has its own database, files, scheduler jobs and backup and restore path, so failover and recovery testing multiply with every site on a bench.	Group only processes that share users and maintenance windows on one site, and confirm with your partner how many sites the failover runbook must cover.
Concurrent users and month-end peaks	Peak load on web workers, MariaDB and Redis during close periods sets the capacity you must keep ready for failover, and it is often the hardest load to test realistically.	Measure concurrency during a real close, then load test the expected peak on staging before sizing the second node.
Data volume and attachment size	Large tables slow replication catch-up and restores, and large attachments enlarge file backups and any file sync between nodes.	Archive or purge old logs where your policy allows, and move attachments to storage that all nodes can reach, confirming how your bench handles that setup.
Custom apps and scheduled jobs	Custom code must be deployed identically on every node, and long-running scheduled jobs can run twice or stall during failover unless their behavior is checked.	Keep custom apps few and tested, shorten long jobs, and document which jobs may run on only one node at a time.
Integrations that call the API	Banking, e-commerce or payroll connectors keep retrying during an outage, which adds load on recovery and can create duplicate records if idempotency is missing.	Use a single documented integration endpoint, add retry limits and confirm how each connector behaves when ERPNext is unreachable.
Number of environments	Production, staging and disaster recovery each need the same versions, custom apps and configuration, so every change is applied and verified more than once.	Keep a staging copy refreshed from production on a fixed schedule and deploy changes through the same steps to every environment.
Regulatory or uptime commitments	Stated recovery time and recovery point targets require documented tests, evidence of restores and a named owner for each step, which adds recurring work.	Agree the targets in writing with your business owners first, then size the design to them rather than adding redundancy by default.
In-house skills	Teams without experience in MariaDB replication, Redis failover and bench operations need more partner time for design, handover and on-call support.	Name an internal owner, schedule handover sessions and ask for runbooks written for your own staff, not only for the implementer.

How to test ERPNext failover and confirm it fails safely

Test failover before anyone needs it, and write down what a pass looks like before each test starts. In a staging environment that matches the production topology as closely as your budget allows, rehearse four failures: loss of one web node, loss of one background worker node, loss of the Redis host, and loss of the MariaDB primary. Run each failure alone first, then combine two in a later round, because outages rarely arrive one at a time. For every case, record the expected outcome, the actual outcome, the time to recover and the person who observed it. A test without a written expectation gets judged by whoever is in the room, and that judgment is hard to review later.

Four checks matter most for each failure. First, users reconnect: sessions that were served by the lost web node should move to a surviving node, and browsers should recover without a forced logout. Watch the features that depend on Socket.io for live updates, since a stale connection can leave a user looking at outdated stock or document status. Second, queued jobs resume without duplicates: after recovery, inspect the background job queue and confirm that a job which posted a ledger entry ran exactly once. Third, the scheduler runs on one node only: confirm from the process list and logs that a single scheduler instance is active across all sites, including after a worker node returns. Check the scheduler service configuration in your Compose or bench setup to confirm this design holds.

Data checks carry most of the weight. Before any promotion, confirm the replica is current by comparing its replication position with the primary's last committed position, and stop write traffic to the primary before taking that reading. Promoting a replica that trails the primary silently drops the most recent transactions, so set a lag threshold in advance and treat anything above it as a failed test. During a switch, have a tester save and submit a set of known test documents, such as a sales invoice and a stock entry, then compare their names and modified timestamps afterward. Separately, restore the latest backup into an isolated environment, confirm the site loads, and check that sample documents match the source. Run the restore on the same schedule as the failover drills.

A failed failover should fail safely. Users should see either a clear error page or a read-only view, and no two database nodes should accept writes at the same time. ERPNext does not decide this on its own, so confirm what your proxy and application tier do when the primary or Redis is unavailable. Send a request during the outage and capture exactly what the user sees. Verify that no site accepts writes on a node that is not the current primary, since that condition produces conflicting records. For review, keep a dated record for each run: the failure injected, timestamps for detection and recovery, log excerpts, screenshots of error pages, the replica position check, the document comparison results, the restore outcome and the sign-off. Store these alongside your change records so internal reviewers or external auditors can trace each test from start to finish.

Securing replicas, Redis and internal traffic in an HA setup

A high availability ERPNext setup multiplies the places where database credentials, Redis access and site secrets live. The cards below cover the access controls and secret handling that every extra node, replica and load balancer needs, so that resilience does not come at the cost of a wider attack surface.

Least privilege replication user

Replication needs its own database account with only the privileges the replica requires, separate from the application account that ERPNext uses for site traffic. Confirm with your MariaDB version's documentation which replication grants apply, restrict the account to the replica host addresses, and review whether the application account holds any administrative privileges it does not need.

Encrypted database connections

Traffic between ERPNext application nodes and the database, and between primary and replica, can cross networks that other teams manage. Decide which links must use TLS, provision server and client certificates, and verify on each node that connections are actually encrypted rather than assuming the setting took effect.

Redis access restricted to internal networks

Redis serves cache, queues and realtime data for ERPNext, so it should never be reachable from untrusted networks. Bind it to private interfaces, restrict access with host firewall rules or security groups, and confirm which authentication options your chosen Redis version and deployment method support before relying on them.

Shared storage permissions

When several web or worker nodes read and write the same site files, the mount's ownership and permissions decide who can alter uploads, private files and configuration. Define a single service account, restrict write access to the nodes that need it, and check that the mount is not exported more widely than the cluster requires.

Load balancer TLS termination

The load balancer or reverse proxy in front of ERPNext typically terminates client TLS. Decide whether traffic to the application nodes stays encrypted, which certificates and cipher policies the balancer uses, and how certificate renewal is automated and monitored so that an expired certificate does not take the site offline.

Site secrets kept out of version control

Site configuration holds database passwords, encryption keys and third-party credentials. Keep these in a secrets manager or in files provisioned at deploy time, exclude them from the repository used for custom apps and infrastructure code, and confirm that backups of configuration are stored with the same access controls as the secrets themselves.

What to monitor, upgrade and document after go-live

Go-live is when high availability either holds up or quietly stops working, so the first task is a watch list tied to the components that make failover possible. Start with replica lag on the MariaDB secondary, because a replica that falls behind becomes a failover target with stale data. Watch the Redis queue backlog for the default, long and short queues used by background jobs. A growing backlog usually means workers are slow, stalled or pointed at the wrong Redis instance. Track worker health on every node, including whether each worker process is running and reconnects cleanly after a Redis or database restart. Confirm that the scheduler is enabled on exactly one node and that scheduled jobs run on time, because duplicate or missing scheduled runs are hard to spot from the user interface.

Two signals are easy to miss. Failed background jobs do not usually look like an outage, so review the background jobs and error log views daily during the first weeks, then route their counts into alerting once you know the normal pattern. Disk use on shared storage for files and assets needs an alert well before the volume fills, because a full volume affects every node at once and undoes the redundancy you built. Ask your team or partner to confirm the dashboards, log shipping and alert thresholds they will use, and record a named owner for each alert so that nothing depends on one person's memory.

Upgrades touch the most moving parts, so run them as a planned rolling procedure. Frappe's supported versions page lists version 15 as supported until the end of 2027 and version 16 until the end of 2029, and version 14 reached end of life on January 31, 2026. Both supported lines receive frequent minor releases, for example v16.51.1 on October 15, 2026 and v15.123.0 on October 14, 2026, so schedule a recurring minor update window and treat it as routine. Run bench update and bench migrate on a staging copy that matches your node layout and custom apps first. In production, take one web node out of rotation, update it and its workers, verify it, return it to service, and only then move to the next node. Confirm with your partner or Frappe whether your topology supports this order and whether a migration needs a maintenance window.

Four handover documents let your team operate the setup without the people who built it. The runbook lists each service, the start and stop order, the commands for bench update and bench migrate, and the steps to promote the replica. The architecture diagram shows which nodes run web, workers, the scheduler, MariaDB, Redis and shared storage, and how traffic and backups flow between them. The failover contacts list named people, their backups, and the vendor or partner staff who must be called. The test log records each failover drill, what was switched, what failed, and the ERPNext version tested. For upgrade steps and rollback detail, see the ERPNext upgrades and support topic. For backup and restore procedures, see the ERPNext backup and disaster recovery topic.

Questions teams ask before building ERPNext high availability

Does adding a second web server give ERPNext high availability?

No. A second web server only removes one point of failure in the request layer. Every web process still depends on the same MariaDB database, the same Redis instance, the same background workers and scheduler, and the same bench file system. If the database or Redis stops, both web servers stop serving users. A high availability design has to cover each of these components, decide how failover happens for the database and Redis, make sure workers and the scheduler do not run twice, and share or replicate uploaded files. Ask your engineers to map every shared dependency before counting servers.

How much does a high availability ERPNext setup cost to run?

The software has no license fee. ERPNext is GPL-3.0, so your costs come from infrastructure, labor and support. Infrastructure includes compute for web, worker and database nodes, load balancing, block or file storage, database replicas, backup storage and network egress. Labor includes the design and build, testing, and ongoing administration. Some costs are one-time, such as design, migration and failover testing. Others recur, such as servers, backups, monitoring, patching and upgrades. Costs rise with the number of environments, data volume, custom apps and the uptime target you set. For a reference point, the ERPNext pricing page lists Frappe Cloud shared hosting from 5 US dollars per month and dedicated servers from 125 US dollars per month. Ask any partner for a quote that separates one-time and recurring items.

How long does it take to set up ERPNext high availability?

The duration depends on what you already run and what you require. The main drivers are the current architecture, whether you start from a single bench or a Docker setup, the number of environments needed for testing, the number and complexity of custom apps, the data volume that must replicate, and how many failover scenarios you want tested. Your internal team's availability also matters. DeployOpen gives a duration only as a fixed-scope estimate after reviewing your environment and written requirements. Before that review, treat any number you hear as an opinion. Ask for the assumptions behind the estimate, the test scenarios included, and the milestones where you sign off.

Can our internal team build ERPNext high availability on its own?

Yes, if the team already has the core skills. The work needs solid Linux administration, MariaDB replication and failover, Redis configuration, Nginx and TLS, and enough familiarity with the Frappe bench commands to deploy and migrate sites. The usual gaps are Frappe-specific behavior: how background jobs and the scheduler behave when several nodes run, how bench migrate interacts with replicas, how custom apps are packaged for upgrades, and how to test failover without losing data. Another gap is time for testing. A failover plan that has never been run is an assumption. Decide which skills are missing and whether your team can cover them while keeping normal operations running.

What must our team provide before high availability work starts?

Most of the delay in these projects comes from missing inputs. Plan to provide access to the target cloud accounts, data centers or air-gapped network, along with an environment plan that includes at least one non-production copy. You will need a staging copy of production data, handled under your data protection rules, so that failover and migration tests use realistic volumes. Name a technical owner who can approve changes, and a business owner who can make decisions about uptime targets, acceptable data loss and maintenance windows. Also provide the list of custom apps, integrations and scheduled jobs, plus your current backup policy and restore records.

Is self-hosting ERPNext free, and what do we still pay for?

Self-hosting the software is free. ERPNext is licensed under GPL-3.0, and the Frappe Framework is licensed under MIT, so you do not pay a license fee to run it. You still pay for the infrastructure that hosts it, for staff time to administer it, and for any outside help. Those costs include servers or cloud resources, backups, monitoring, security updates, upgrades, custom app maintenance and implementation. Frappe's own support is separate. Frappe states that warranty coverage requires your version to be listed as supported and a matching Frappe Cloud support plan. Check which parts of your operating model would change if you chose a managed hosting option instead.

Should we use Frappe Cloud or self-host for high availability?

The choice depends on who must own the architecture, data location and operations. Frappe Cloud is Frappe's hosted service, with shared hosting from 5 US dollars per month and dedicated servers from 125 US dollars per month according to the ERPNext pricing page. Self-hosting gives you control over the infrastructure, network placement and data residency, and it means your team or partner designs and runs the high availability layer. Before choosing, confirm with Frappe which high availability features its plans include, what the failover behavior is, and what restore options exist. DeployOpen implements, hardens and supports self-hosted platforms inside your own cloud accounts, data centers or air-gapped networks.

How DeployOpen scopes, builds and hands over ERPNext high availability

DeployOpen approaches ERPNext high availability as a fixed-scope engagement inside your own infrastructure, starting with an agreed written scope and a map of how your web, database, cache and background processes depend on each other. The work ends with a documented setup your team can operate, test and extend.

How we scope

Map current bench layout, MariaDB, Redis, worker, scheduler and web process placement before proposing changes
Agree in writing which failure scenarios the setup must survive, such as a web node or database host going down
Confirm hosting target, whether your own servers, cloud accounts or a Frappe Cloud plan, and who operates each layer

How we build

Separate MariaDB, Redis, background workers and web processes onto the hosts agreed in the scope
Configure database replication and backup jobs, then test restores on a staging copy before go-live
Size and scale background workers for queue load, and check custom apps still run under the new topology

How we hand over

Deliver an architecture document, runbook and configuration files covering each service and its dependencies
Run and record failover, restore and worker scaling tests against the acceptance criteria in the written scope
Train your administrators on routine checks, bench update and migrate steps, and the escalation path for incidents

How we support

Offer ongoing support, upgrades and testing as a retainer after handover, with scope agreed separately
Review the setup when moving between ERPNext versions, since supported releases receive frequent minor updates
Confirm with Frappe which support plan and version matter for your warranty position before relying on either

ERPNext high availability