Site backup and restore were introduced in EasyEngine v4.9.0, and this page is updated for the changes in v4.14.0.
ee site backup saves a site to remote storage and ee site restore puts it back. EasyEngine uses rclone to talk to the storage; this page sets it up for Amazon S3 or S3-compatible storage. It applies to servers you manage with ee.
If EasyEngine Dashboard manages the server, set up backup storage in the Dashboard instead, under Settings and Backup Provider. See Backups & Restore FAQs.
Set up S3 storage
Any S3-compatible storage works as the backup backend. The example below uses Amazon S3 (AWS); other providers need two extra settings, shown after the example.
EasyEngine doesn’t install rclone. Install it on the server first, using one of the methods on rclone’s download page, then check it runs:
rclone --version
Create an rclone remote for your S3 bucket. Run rclone as the same user that runs ee, since rclone reads that user’s configuration file. The keys below are placeholders:
rclone config create easyengine s3 provider=AWS access_key_id=YOUR_ACCESS_KEY_ID secret_access_key=YOUR_SECRET_ACCESS_KEY region=us-east-1
rclone config asks the same questions interactively. For other S3-compatible storage, use the same s3 backend: set provider to your provider, or Other, and add its endpoint. See rclone’s Amazon S3 documentation for every option.
rclone listremotes should now show easyengine:.
Then tell EasyEngine where to store backups. rclone-path in /opt/easyengine/config/config.yml takes the form remote:bucket/path:
ee config set rclone-path easyengine:my-bucket/ee-backups
If rclone-path isn’t set, EasyEngine uses easyengine:easyengine: a remote named easyengine and a bucket named easyengine. The remote name must match an entry of rclone listremotes exactly.
Back up a site
ee site backup example.com
Backups work for WordPress, PHP and HTML sites, and the site must be enabled. Before anything else, EasyEngine checks that /opt/easyengine/.backup has room for the site’s app/ directory and its database. It then dumps the database, builds the archives in that directory, tests them and uploads them to:
<rclone-path>/<site>/<host-id>/<backup-id>
The host id names this server (see Moving or replacing a server). The backup id is the time of the backup, such as 1794836000_2026-11-16-13-33-20. A server runs one backup at a time; another ee site backup waits for it to finish.
A backup holds:
- WordPress sites: all of
app/except WordPress core and tool caches, sowp-config.php,wp-contentand files such asrobots.txt, verification files and.user.iniare included. A restore downloads WordPress core again at the backup’s version. If that version can’t be downloaded again (a nightly build, for example) or can’t be read, core is included in the backup, with a warning. - PHP and HTML sites: all of
app/. - The database, for sites that have one.
- The site’s nginx configuration, its PHP configuration (PHP and WordPress sites) and any custom docker-compose files.
- The site’s details, without its passwords.
A backup stops before upload if the archive fails its test, or if the database dump fails or is empty. If a WordPress site’s wp-content/uploads links outside the site directory, the backup holds only the link, with a warning; back up those files separately.
List backups
ee site backup example.com --list
The list shows this server’s backups first, newest first, then backups made before v4.14.0, then other servers’ backups as <host-id>/<backup-id>. A backup whose upload was interrupted is not listed, and a warning names it. If there are none, the command prints No remote backups found.
Restore a site
ee site restore example.com
Without --id, a restore takes this server’s newest backup. To restore another backup, pass an id from the list:
ee site restore example.com --id=1794836000_2026-11-16-13-33-20
A backup made on another server is restored with --id=<host-id>/<backup-id>.
The site must exist on the server, be enabled, and have the same site type as the backup. A restore looks for backups under the site’s own name, so to restore onto a new server, create the site with the same domain and type first.
Before it changes anything, a restore checks:
- Free space in
/opt/easyengine/.backupfor the download. - Free space next to the site for the extracted backup and a copy of the current database (and WordPress core, when it is downloaded again).
- That nothing is mounted inside the site’s
app/directory, for example uploads. Unmount it first. - That the backup’s site type and database match the site.
A restore then replaces:
- All of the site’s
app/directory, so files created after the backup are removed. For WordPress this applies to backups made by v4.14.0, and WordPress core is downloaded again at the backup’s version. WordPress backups made before v4.14.0 replacewp-config.php,wp-content, WordPress core and the database, and leave the site’s other files as they are. - The database: the backup’s tables are imported. Tables created after the backup stay in the database.
- The site’s nginx and PHP configuration and custom docker-compose files, from the backup.
wp-config.php keeps the current site’s database credentials. The restored nginx configuration has to pass nginx -t.
If a step fails before the backup is fully in place, the site goes back to how it was before the restore started, and the restore says so. The container restart at the end comes after that point, so a failed restart is not rolled back: the restored site stays in place, and ee site restart example.com starts it again.
If a restore is killed before it finishes, ee site backup refuses to back up the half-restored site. Remove the lock file the error names if no backup or restore is running, then run ee site restore example.com: it rolls the earlier restore back first, then restores the backup. Back up again afterwards.
Retention
EasyEngine keeps the newest 7 backups of each site in this server’s folder and deletes older ones after each successful backup. The backup just uploaded is never deleted. Change the number with no-of-backups:
ee config set no-of-backups 14
A value that isn’t a whole number of at least 1 falls back to 7, with a warning. Backups made before v4.14.0 and other servers’ backups are never deleted automatically. An upload that stopped partway is removed by the next successful backup.
Moving or replacing a server
Each server keeps its backups in its own host id folder, so several servers can share one rclone-path. The host id is created on the server’s first backup or restore and kept in the EasyEngine database. A reinstall starts a new host id, and a server copied with its EasyEngine database has the same one.
To choose the host id, set backup-host-id:
ee config set backup-host-id my-server
It takes up to 63 letters, digits, ., _ or -, starting with a letter or digit. An invalid value stops backups and restores with an error.
To replace a server, either set backup-host-id on the new server to the old server’s host id, so it keeps backing up into the same folder and restores its backups by default, or restore once with --id=<old-host-id>/<backup-id>. Do not give two running servers the same host id, since they would prune and restore each other’s backups.
Backups made before v4.14.0
Older versions stored backups at <rclone-path>/<site>/<backup-id>. They stay there, and v4.14.0 lists them and restores them with --id=<backup-id>. Without --id, a restore takes the newest of them only if this server has no backup in its own folder yet, with a warning.
They are not pruned, since they may belong to another server using the same rclone-path. Remove them by hand once you no longer need them:
rclone lsf --dirs-only <rclone-path>/example.com/
rclone purge <rclone-path>/example.com/<backup-id>
The first command lists host id folders too; never purge one of those. Scripts that build <rclone-path>/<site>/<backup-id> paths need the host id folder added for backups made by v4.14.0.
Servers on older versions
EasyEngine versions before v4.14.0 don’t list or restore backups made by v4.14.0, for any site type. Without --id, they restore the newest backup made before v4.14.0 instead. Update every server that restores these backups with ee cli update; ee cli version shows the version a server runs.
Troubleshooting
rclone is not installed: install rclone as shown in Set up S3 storage.rclone backend "easyengine" does not exist: the remote named inrclone-pathis missing fromrclone listremotesfor the user runningee. Create it, or setrclone-pathto a remote that exists.Another backup/restore process is running: wait for it to finish. If none is running, for example because one was killed, remove the lock file the error names.An earlier restore of example.com did not finish: runee site restore example.com, which rolls the earlier restore back first, then back up again.Not enough disk space to take backuporNot enough disk space to restore backup: the error shows how much space is needed. Free up space and run the command again.These mount points are inside the site directory: unmount them, then restore again. The site was not changed.Invalid backup-host-id: fix or removebackup-host-idin/opt/easyengine/config/config.yml.
Still stuck? Open a support ticket.