bench setup backups

The bench setup backups command configures a cron job to automatically back up all sites in your bench every 6 hours.

Usage

bench setup backups

This command takes no arguments or options.

What It Does

Determine Cron User

Reads the frappe_user from sites/common_site_config.json.If not set, uses the current system user.

Create Backup Command

Generates a command to back up all sites:

cd /home/frappe/frappe-bench && bench --verbose --site all backup

Add Cron Job

Adds a cron job to the user’s crontab:

0 */6 * * * cd /path/to/bench && bench --verbose --site all backup >> logs/backup.log 2>&1

Configure Logging

Logs backup output to logs/backup.log in the bench directory.

Backup Schedule

By default, backups run:

Every 6 hours (at 00:00, 06:00, 12:00, and 18:00)
For all sites in the bench
With verbose output logged to file

Examples

Basic Setup

Schedule automatic backups:

bench setup backups

Output:

Setting Up cron job to bench auto backups set for every 6 hours
Backups Cronjob Set Up

Verify Cron Job

Check that the cron job was created:

crontab -l

You should see:

# bench auto backups set for every 6 hours
0 */6 * * * cd /home/frappe/frappe-bench && bench --verbose --site all backup >> /home/frappe/frappe-bench/logs/backup.log 2>&1

View Backup Logs

Monitor backup execution:

tail -f ~/frappe-bench/logs/backup.log

Backup Files

Backup Location

Backups are stored in each site’s private directory:

sites/[sitename]/private/backups/
├── 20240301_120000-site1_local-database.sql.gz
├── 20240301_120000-site1_local-files.tar
└── 20240301_120000-site1_local-private-files.tar

Backup Contents

Each backup includes:

Database backup: Compressed SQL dump (.sql.gz)
Public files: Site files from public/files (.tar)
Private files: Site files from private/files (.tar)

Backup Naming

Format: YYYYMMDD_HHMMSS-[sitename]-[type].[ext] Example:

20240301_120000-site1_local-database.sql.gz

Backup Configuration

Backup Retention

Configure how many backups to keep in site_config.json:

{
  "backup_limit": 3
}

Older backups are automatically deleted.

Exclude Files

Skip file backups (database only):

{
  "backup_with_files": false
}

Offsite Backups

S3 / AWS

Configure S3 for automatic offsite backups:

{
  "s3_backup_enabled": true,
  "s3_backup_bucket": "my-bucket",
  "aws_access_key_id": "YOUR_KEY",
  "aws_secret_access_key": "YOUR_SECRET",
  "s3_backup_region": "us-east-1"
}

Dropbox

{
  "dropbox_backup_enabled": true,
  "dropbox_access_token": "YOUR_TOKEN",
  "dropbox_backup_path": "/backups"
}

Google Drive

{
  "gdrive_backup_enabled": true,
  "gdrive_credentials": "/path/to/credentials.json"
}

Custom Backup Schedule

To customize the backup schedule, edit the cron job:

crontab -e

Daily Backups

Run once daily at 2 AM:

0 2 * * * cd /home/frappe/frappe-bench && bench --verbose --site all backup >> /home/frappe/frappe-bench/logs/backup.log 2>&1

Hourly Backups

Run every hour:

0 * * * * cd /home/frappe/frappe-bench && bench --verbose --site all backup >> /home/frappe/frappe-bench/logs/backup.log 2>&1

Weekly Backups

Run every Sunday at midnight:

0 0 * * 0 cd /home/frappe/frappe-bench && bench --verbose --site all backup >> /home/frappe/frappe-bench/logs/backup.log 2>&1

Multiple Backup Times

Run at 2 AM and 2 PM daily:

0 2,14 * * * cd /home/frappe/frappe-bench && bench --verbose --site all backup >> /home/frappe/frappe-bench/logs/backup.log 2>&1

Manual Backups

Backup All Sites

bench --site all backup

Backup Specific Site

bench --site site1.local backup

Backup Without Files

bench --site site1.local backup --only-db

Backup With Compression

bench --site site1.local backup --with-files --compress

Restore from Backup

Restore Database

bench --site site1.local --force restore /path/to/backup.sql.gz

Restore with Files

bench --site site1.local --force restore \
  --with-private-files /path/to/private-files.tar \
  --with-public-files /path/to/files.tar \
  /path/to/database.sql.gz

Monitoring

Check Backup Status

View recent backups:

ls -lht ~/frappe-bench/sites/site1.local/private/backups/ | head

Backup Size

Check total backup size:

du -sh ~/frappe-bench/sites/*/private/backups

Backup Age

Find backups older than 7 days:

find ~/frappe-bench/sites/*/private/backups -name "*.sql.gz" -mtime +7

Troubleshooting

Backups Not Running

Check if cron job exists:
```
crontab -l | grep backup
```
Check cron service:
```
sudo systemctl status cron
```

Check backup logs:

tail -100 ~/frappe-bench/logs/backup.log

Permission Issues

If backups fail with permission errors:

# Fix ownership
sudo chown -R frappe:frappe ~/frappe-bench

# Fix permissions
chmod -R 755 ~/frappe-bench/sites/*/private/backups

Disk Space Issues

If backups fail due to insufficient disk space:

# Check disk usage
df -h

# Clean old backups
find ~/frappe-bench/sites/*/private/backups -name "*.sql.gz" -mtime +30 -delete

# Reduce backup retention
bench --site site1.local set-config backup_limit 2

Cron Not Running

If cron isn’t executing backups:

# Ensure cron is running
sudo systemctl start cron
sudo systemctl enable cron

# Check cron logs
sudo tail -f /var/log/syslog | grep CRON

# Test backup manually
cd ~/frappe-bench
bench --verbose --site all backup

Remove Backup Cron

To disable automatic backups:

# Edit crontab
crontab -e

# Remove or comment out the backup line:
# 0 */6 * * * cd /home/frappe/frappe-bench && bench --verbose --site all backup >> /home/frappe/frappe-bench/logs/backup.log 2>&1

Best Practices

Test Restores Regularly

Periodically test backup restoration to ensure backups are valid:

# Create test site
bench new-site test.local

# Restore from backup
bench --site test.local --force restore /path/to/backup.sql.gz

# Verify
bench --site test.local migrate

# Clean up
bench drop-site test.local

Monitor Backup Size

Set up alerts for backup size anomalies:

# Create monitoring script
#!/bin/bash
MAX_SIZE=1000000  # 1GB in KB
BACKUP_SIZE=$(du -s ~/frappe-bench/sites/*/private/backups | awk '{print $1}')

if [ $BACKUP_SIZE -gt $MAX_SIZE ]; then
  echo "Warning: Backup size exceeds threshold" | mail -s "Backup Alert" [email protected]
fi

Use Offsite Storage

Always maintain offsite backups:

Configure S3, Dropbox, or Google Drive
Use separate cloud provider from hosting
Encrypt sensitive backups
Test offsite backup restoration

Implement 3-2-1 Rule

Follow the 3-2-1 backup rule:

3 copies of data
2 different storage types
1 copy offsite

Example:

Local server backups (automatic)
S3 backups (automatic)
Weekly manual backups to external drive

bench backup - Manually create backups
bench restore - Restore from backup
bench --site all backup - Backup all sites

Source Code

Implementation: bench/bench.py:471 Command definition: bench/commands/setup.py:113

Get Started

Core Commands

Setup Commands

Config Commands

Utility Commands

Guides

Advanced

​Usage

​What It Does

​Backup Schedule

​Examples

​Basic Setup

​Verify Cron Job

​View Backup Logs

​Backup Files

​Backup Location

​Backup Contents

​Backup Naming

​Backup Configuration

​Backup Retention

​Exclude Files

​Offsite Backups

​S3 / AWS

​Dropbox

​Google Drive

​Custom Backup Schedule

​Daily Backups

​Hourly Backups

​Weekly Backups

​Multiple Backup Times

​Manual Backups

​Backup All Sites

​Backup Specific Site

​Backup Without Files

​Backup With Compression

​Restore from Backup

​Restore Database

​Restore with Files

​Monitoring

​Check Backup Status

​Backup Size

​Backup Age

​Troubleshooting

​Backups Not Running

​Permission Issues

​Disk Space Issues

​Cron Not Running

​Remove Backup Cron

​Best Practices

​Related Commands

​Source Code

Build docs developers (and LLMs) love