How to Backup and Restore ERPNext Properly

A Complete Technical & Production-Level Guide

1. Understanding ERPNext Backup Architecture

Backup architecture in ERPNext is designed around the separation of database data and file storage. Every ERPNext site contains structured database records stored in MariaDB and file-based assets such as attachments, private documents, and public files stored inside the site directory. The bench framework orchestrates backup processes through internal utilities that dump SQL data and compress file directories. A proper backup strategy must include three components: database dump, public files backup, and private files backup. Failing to back up any one of these components results in incomplete disaster recovery. Database backups ensure transactional integrity, while file backups preserve attachments, print formats, and custom uploaded documents. Understanding this separation is critical before implementing production-grade backup automation.

Backup Components

Component	Description
Database Backup	SQL dump of MariaDB data
Public Files	Files accessible without authentication
Private Files	Secure attachments requiring login

Site Directory Structure

frappe-bench/
 ├── sites/
 │    ├── site1.local/
 │    │    ├── private/
 │    │    ├── public/
 │    │    ├── site_config.json

Architecture Workflow

1. User data stored in database.
2. Attachments stored in site folders.
3. Bench backup command generates SQL dump.
4. Files compressed into archive.
5. Backup stored inside site/private/backups.

2. Manual Backup Using Bench Command

ERPNext provides a built-in bench command to perform full site backup. This command creates a SQL dump using mysqldump and compresses public and private file directories into tar archives. The generated backup files are stored under sites/site_name/private/backups directory. The command ensures consistency by locking database tables during dump generation. Manual backup is useful before major upgrades, app installations, migrations, or configuration changes.

Manual Backup Command

bench --site site1.local backup

Generated Backup Files

File Type	Example Name
Database Dump	20250918_120000-site1.local-database.sql.gz
Private Files	20250918_120000-site1.local-private-files.tar
Public Files	20250918_120000-site1.local-files.tar

Workflow

1. Navigate to frappe-bench directory.
2. Execute bench backup command.
3. Verify backup files created.
4. Download to secure external storage.

3. Automating Scheduled Backups

In production environments, manual backups are insufficient. Automated scheduled backups ensure data protection without human intervention. ERPNext supports daily scheduled backups through the scheduler configuration. Backup settings can be configured from System Settings to define frequency and retention policy. Alternatively, system-level cron jobs can execute bench backup commands. Best practice recommends storing backups off-server (e.g., AWS S3, remote FTP, or network storage) to prevent data loss due to server failure.

Enable Scheduled Backups (UI)

1. Go to System Settings.
2. Enable Scheduled Backup.
3. Set frequency (Daily/Weekly).
4. Define number of backups to retain.

Cron-Based Backup Example

0 2 * * * cd /home/frappe/frappe-bench && bench --site site1.local backup

Best Practice Table

Strategy	Purpose
Daily Backup	Protect daily transactions
Offsite Storage	Disaster recovery
Retention Policy	Storage optimization

4. Restoring ERPNext from Backup

Restoring ERPNext involves reloading the SQL dump and extracting file archives into the correct site directory. Restoration should be performed on a clean site environment to prevent data conflicts. The bench restore command imports the SQL dump into MariaDB and ensures schema compatibility. File archives must be manually extracted into public and private folders. After restoration, the system must be restarted to reinitialize services.

Restore Command

bench --site site1.local restore backup.sql.gz

Extract Files

tar -xvf private-files.tar -C sites/site1.local/private/
tar -xvf public-files.tar -C sites/site1.local/public/

Restore Workflow

1. Create fresh site (if needed).
2. Run restore command.
3. Extract file backups.
4. Run bench migrate.
5. Restart services.
6. Verify login and data integrity.

5. Restoring Backup to a New Server Environment

Restoring ERPNext to a new server is a common requirement during infrastructure migration, scaling, cloud migration, or disaster recovery scenarios. The restoration process involves setting up a fresh Frappe bench environment, installing ERPNext app, creating a new site, and importing the SQL dump along with file backups. It is critical to ensure that the MariaDB version, Python version, Node version, and ERPNext app version are compatible with the original environment. Version mismatches may cause migration failures or schema conflicts. Before restoring, administrators should validate site_config.json values, database credentials, and installed apps. After restoration, running bench migrate ensures that database schema aligns with current app version.

New Server Setup Workflow

1. Install Python, Node.js, Redis, and MariaDB.
2. Install Frappe Bench.
3. Create new bench environment.
4. Install ERPNext app.
5. Create empty site.
6. Restore SQL dump.
7. Extract file backups.
8. Run bench migrate.

Example Commands

bench init frappe-bench
cd frappe-bench
bench get-app erpnext
bench new-site site1.local
bench --site site1.local install-app erpnext
bench --site site1.local restore backup.sql.gz
bench migrate

Compatibility Checklist

Component	Must Match
ERPNext Version	Yes
Frappe Framework Version	Yes
MariaDB Major Version	Recommended
Python Version	Compatible

6. Backup Encryption and Security Best Practices

Backups contain highly sensitive business data including financial records, payroll details, customer information, and authentication metadata. Therefore, encryption and secure storage are mandatory in production environments. ERPNext does not automatically encrypt backup files, so administrators must implement external encryption mechanisms such as GPG or encrypted storage volumes. Access control must restrict who can download or access backup directories. Offsite backups should be transferred over secure channels such as SFTP or HTTPS. Additionally, private keys and site_config.json must be protected to prevent unauthorized system access.

Encrypt Backup Using GPG

gpg -c 20250918_120000-site1.local-database.sql.gz

Secure Transfer Example

scp backup.sql.gz.gpg user@remote-server:/secure-backups/

Security Control Table

Control	Purpose
Encryption	Protect sensitive data
Restricted Access	Limit download permissions
Secure Transfer	Prevent interception
Offsite Storage	Disaster resilience

7. Incremental vs Full Backup Strategy

Backup strategy selection depends on system size and recovery requirements. Full backups capture entire database and file system at a specific point in time. Incremental backups capture only changes since last backup, reducing storage consumption. ERPNext’s default bench backup performs full backup. However, system-level incremental backup can be implemented using binary log (binlog) in MariaDB or filesystem-level snapshot tools. Combining daily full backups with hourly incremental backups ensures minimal data loss while optimizing storage efficiency.

Binary Log Configuration (MariaDB)

[mysqld]
log-bin=mysql-bin
server-id=1
expire_logs_days=7

Strategy Comparison

Backup Type	Pros	Cons
Full Backup	Complete recovery	Large storage usage
Incremental Backup	Storage efficient	Complex restoration

Recommended Enterprise Strategy

1. Daily full backup.
2. Hourly binlog incremental backup.
3. Weekly offsite replication.
4. Monthly archival backup.

8. Disaster Recovery Planning for ERPNext

Disaster Recovery (DR) planning ensures business continuity in case of hardware failure, cyberattack, or natural disaster. ERPNext DR strategy must define Recovery Point Objective (RPO) and Recovery Time Objective (RTO). RPO defines maximum acceptable data loss window, while RTO defines acceptable downtime duration. High-availability setups may use database replication, load balancers, and standby servers. Backup validation testing must be performed regularly by restoring backups in staging environments. DR documentation should clearly outline recovery steps, contact persons, and escalation procedures.

Disaster Recovery Plan Components

Component	Description
RPO	Maximum tolerable data loss time
RTO	Maximum tolerable downtime
Offsite Backup	Remote storage location
Recovery Testing	Periodic restoration validation

DR Testing Workflow

1. Take production backup.
2. Restore to staging server.
3. Verify login and functionality.
4. Run financial reports.
5. Validate file attachments.

9. Database-Level Backup Using mysqldump

Although the bench backup command internally uses mysqldump, enterprise administrators may sometimes require direct database-level control for granular backup strategies, replication, or integration with external monitoring systems. Using mysqldump allows database-only backup without compressing file storage. This method is particularly useful when integrating ERPNext database backup with centralized enterprise backup tools. The mysqldump utility exports the entire database schema along with transactional data into an SQL file that can later be restored using mysql import. Care must be taken to use --single-transaction for InnoDB tables to maintain consistency without locking tables for long durations. Administrators should also include --routines and --events if stored procedures or scheduled events are configured.

mysqldump Command Example

mysqldump -u root -p --single-transaction --routines --events site1_local > site1_backup.sql

Restore Using mysql

mysql -u root -p site1_local < site1_backup.sql

Database Backup Best Practices

Option	Purpose
--single-transaction	Ensures consistency without locking
--routines	Includes stored procedures
--events	Includes scheduled DB events
Compression (.gz)	Reduces storage size

When to Use Direct mysqldump

1. Enterprise centralized backup integration.
2. Database-only replication scenarios.
3. External monitoring system requirements.
4. Custom retention policies outside bench framework.

10. File System Backup Strategy for Public and Private Files

ERPNext separates attachments and assets into public and private directories under each site folder. Public files include images, website assets, and downloadable content, while private files include sensitive attachments such as invoices, HR documents, and confidential records. A complete backup must archive both directories. Enterprise administrators may use tar, rsync, or snapshot-based tools for file-level backup. Rsync is particularly useful for incremental file synchronization to remote servers. It is essential to maintain correct file permissions during restoration to prevent access issues.

Archive Public and Private Files

tar -czvf public_files.tar.gz sites/site1.local/public/
tar -czvf private_files.tar.gz sites/site1.local/private/

Incremental File Sync with rsync

rsync -avz sites/site1.local/private/ user@remote-server:/backup/private/

File Backup Strategy Table

Method	Use Case
tar archive	Full snapshot backup
rsync	Incremental sync
Filesystem snapshot	Large-scale production environments

Validation Workflow

1. Archive files.
2. Verify archive size.
3. Transfer to offsite storage.
4. Test extraction in staging.

11. Backup Retention Policy and Storage Optimization

Backup retention policy defines how long backups are stored before deletion. Without a proper retention policy, storage may become exhausted, especially in large ERP deployments. ERPNext allows defining the number of backups to retain via System Settings. However, enterprise environments often implement multi-tier retention strategies: daily backups retained for 7 days, weekly backups for 4 weeks, and monthly backups for 12 months. Storage optimization techniques include compression, deduplication, and archiving older backups to cold storage solutions such as Amazon S3 Glacier.

Retention Strategy Example

Backup Type	Retention Period
Daily Backup	7 days
Weekly Backup	4 weeks
Monthly Backup	12 months

Automatic Cleanup Command

bench --site site1.local trim-backups

Storage Optimization Techniques

1. Enable compression (.gz).
2. Move older backups to cold storage.
3. Delete expired backups automatically.
4. Monitor disk usage regularly.

12. Backup Validation and Integrity Testing

A backup is useless unless it can be successfully restored. Backup validation involves periodically restoring backups in a staging or test environment to ensure integrity. Integrity testing verifies database consistency, file completeness, login functionality, and report generation accuracy. Administrators should validate that restored site loads correctly, users can authenticate, attachments are accessible, and financial reports generate without errors. Automated integrity testing scripts can be implemented to streamline validation. Regular validation ensures disaster recovery readiness and builds operational confidence.

Validation Checklist

Test	Expected Result
Database restore	No SQL errors
User login	Successful authentication
File access	Attachments accessible
Report generation	No data corruption

Testing Workflow

1. Restore backup to staging server.
2. Run bench migrate.
3. Access site via browser.
4. Verify sample transactions.
5. Generate financial report.
6. Confirm file attachments open properly.

13. High Availability and Real-Time Replication Strategy

In mission-critical production environments, relying solely on periodic backups may not be sufficient. High Availability (HA) architecture ensures minimal downtime and near-zero data loss. ERPNext deployments can implement MariaDB replication (master-slave or primary-replica configuration) to maintain real-time database synchronization. In this setup, the primary database handles writes while the replica continuously receives binary log updates. If the primary server fails, traffic can be redirected to the replica server. Additionally, file system synchronization must be implemented using tools like rsync or shared network storage to maintain consistency of public and private file directories. Load balancers and reverse proxies can distribute traffic between application servers to enhance reliability. Implementing HA requires careful monitoring and failover testing to ensure seamless transition during outages.

MariaDB Replication Configuration (Conceptual)

[mysqld]
server-id=1
log-bin=mysql-bin
binlog-do-db=site1_local

Replication Monitoring

SHOW SLAVE STATUS\G

High Availability Components

Component	Purpose
Primary Database	Handles write operations
Replica Database	Maintains synchronized copy
Load Balancer	Distributes traffic
File Sync Tool	Maintains attachment consistency

HA Workflow

1. Enable binary logging on primary DB.
2. Configure replica server.
3. Sync file storage across servers.
4. Test failover scenario.
5. Monitor replication health regularly.

14. Cloud-Based Backup Integration (AWS S3 Example)

Cloud storage provides scalable, durable, and geographically distributed backup storage. ERPNext backups can be uploaded to cloud services such as Amazon S3, Google Cloud Storage, or Azure Blob Storage. Integrating S3 ensures that backups remain safe even if the primary server is compromised. Administrators can use AWS CLI or automated scripts to upload generated backup files. Lifecycle policies can move older backups to cold storage automatically. Secure IAM policies must be configured to restrict access and enforce encryption at rest.

AWS CLI Upload Example

aws s3 cp backup.sql.gz s3://erpnext-backups/site1/

S3 Lifecycle Policy Concept

Rule	Action
After 30 days	Move to Glacier
After 365 days	Delete permanently

Cloud Backup Workflow

1. Install AWS CLI.
2. Configure IAM credentials.
3. Upload backup files automatically via cron.
4. Verify upload status.
5. Test restore from cloud periodically.

15. Common Backup and Restore Errors & Troubleshooting

During backup and restore operations, administrators may encounter errors such as database schema mismatches, version conflicts, missing file directories, or permission errors. A common issue arises when restoring backups to a different ERPNext version without running bench migrate. Another frequent problem involves incorrect file permissions preventing ERPNext from accessing restored files. SQL errors during restore may indicate incompatible MariaDB versions or corrupted dumps. Proper troubleshooting requires reviewing bench logs, MariaDB logs, and system permissions.

Common Errors Table

Error	Cause	Solution
Unknown column error	Version mismatch	Run bench migrate
Access denied	Wrong DB credentials	Update site_config.json
Permission denied (files)	Incorrect ownership	Fix with chown
Import failed	Corrupted SQL dump	Recreate backup

Fix File Permissions

sudo chown -R frappe:frappe sites/site1.local

Troubleshooting Workflow

1. Check bench logs.
2. Verify database credentials.
3. Confirm ERPNext version compatibility.
4. Run bench migrate.
5. Restart services.

16. Enterprise Backup Governance and Documentation

Backup governance ensures that procedures are standardized, documented, and consistently followed across the organization. Enterprise IT teams should maintain detailed documentation outlining backup frequency, storage locations, encryption standards, restoration procedures, and responsible personnel. Governance also includes periodic audit reviews to verify compliance with regulatory requirements. Documentation should define escalation procedures during data loss incidents. Clear governance reduces dependency on individual administrators and ensures operational continuity.

Governance Documentation Elements

Document Element	Description
Backup Schedule	Frequency and timing
Retention Policy	Storage duration rules
Encryption Policy	Security standards
Recovery Procedure	Step-by-step restore plan
Responsible Personnel	Assigned IT roles

Governance Workflow

1. Define backup standards.
2. Assign responsibility.
3. Document recovery steps.
4. Conduct periodic audits.
5. Update procedures after system changes.

Conclusion: Building a Resilient ERPNext Backup & Recovery Strategy

A robust backup and restore strategy in ERPNext is not merely a technical task but a critical component of enterprise risk management. From basic bench backups to advanced database replication, encrypted storage, cloud integration, high availability configurations, and governance documentation, every layer contributes to operational resilience. Backup processes must be automated, validated, encrypted, and stored offsite to protect against hardware failures, cyber threats, and natural disasters. Regular restoration testing ensures backup reliability, while proper retention policies optimize storage efficiency. By implementing structured disaster recovery planning and governance standards, organizations can ensure business continuity, regulatory compliance, and long-term system stability. When executed correctly, ERPNext backup architecture transforms from a simple maintenance routine into a comprehensive enterprise-grade data protection framework.