Backups
Full and incremental backups, encrypted S3 copies, database backups and customer schedules, plus how to restore an account, a file or a database.
ZoPanel has several kinds of backups that work together. Full account backups give you a complete archive you can move to any ZoPanel server. Incremental snapshots (restic) are small nightly copies you can restore one file at a time. Database backups can run as often as every hour. Every archive can also be copied, encrypted, to S3-compatible storage. This page covers the setup, the safety checks and every way to restore.
Overview
| Kind | Contents | Schedule | Where |
|---|---|---|---|
| Full account backup | Websites, databases (MariaDB, PostgreSQL, MongoDB, Redis) and email of one account | Manual, or daily/weekly at 02:00 | ~/backups of the account, plus S3 |
| Incremental snapshot (restic) | Files, databases and mail of every account | Nightly at 01:00 | /var/backups on the server, or S3 |
| Database backup | One database, of any engine | Every hour, every 6 hours or daily | backups/db of the account, plus S3 |
| Customer schedule | Files, databases and mail, as the customer chooses | Daily or weekly, at a chosen hour | The account, and optionally the customer's own S3 |
Configuration backup (.zpb) |
Panel settings and database | Daily | S3 (see Disaster recovery) |
| App backup | One App Store app's data, or the S3 storage component | Manual, or daily/weekly | /var/backups/zopanel-apps on the server (root only) |
App Store apps and S3 storage have their own backups. Account backups, database backups, customer schedules and incremental (restic) snapshots cover website folders, databases and mailboxes only. They do not contain App Store app data (/var/lib/zopanel-apps/<instance>/) or S3 storage buckets (/var/lib/zopanel-storage). These are backed up from their own Backups card instead: see App and S3 storage backups.
Full account backups
On the Backups page, choose an account and click Create backup. All websites, databases and email of the account are archived into ~/backups.
What is in an account backup
The archive (backup-<date>.tar.gz) holds:
| Path in the archive | What | How |
|---|---|---|
domains/<domain>/ |
Every file of each website, including apps deployed from git with their virtualenv or node_modules |
As the files are; links are kept as links |
databases/<name>.sql |
Each MariaDB database | mariadb-dump (single transaction, routines, triggers) |
databases/<name>.pgsql |
Each PostgreSQL database | pg_dump plain SQL (--clean --if-exists --no-owner --no-acl), made as the account through a role with only the database owner's rights |
databases/<name>.mongo |
Each MongoDB database | A mongodump archive of that database only, made by a temporary user that may only read it |
databases/<name>.redis |
Each Redis database | Its keys (<user>:* on the shared Redis), with their values and expiry |
mail/<domain>.tar |
Each email domain's mailboxes and messages | |
manifest.json |
The account, its websites and the list of databases with their engine | Lets Restore from file recreate the account on another server |
Not in an account backup:
- App Store apps and S3 storage: they have their own backups (see App and S3 storage backups). The Backups list does not show them among the websites of an account backup.
- Databases on an external database server: they are not on this server.
- The WordPress object cache: it is a cache (the account's own Redis instance keeps nothing on disk). After a database is restored, the object cache of the WordPress sites using it is emptied, so the sites show the restored data at once.
The Contents column of the Backups list counts the databases by engine (for example 2 MariaDB, 1 PostgreSQL); hover a badge to see their names.
To back up every account automatically, open Settings → General:
- Automatic backups: Off, Daily or Weekly (Sunday). Backups run at 02:00 server time.
- Backups to keep per account: 1 to 90 (default 7).
Before a backup starts, ZoPanel checks the free disk space. It refuses to start when less than 1 GB, or less than 5% of the disk, is free, so a backup can never fill the disk and take the websites down. Each finished archive gets a SHA-256 checksum, which is checked again before any restore.
Remote backups to S3
Remote backups need a Pro license. Open Settings → Remote backups, turn the switch on and fill in:
| Field | Notes |
|---|---|
| Provider presets | AWS, Cloudflare R2, Backblaze B2, Wasabi, MinIO and others |
| Endpoint, Region, Bucket | From your storage provider |
| Folder prefix | Defaults to zopanel |
| Access key, Secret key | Use a key limited to this bucket |
| Remote copies to keep per account | 1 to 365 (default 14) |
| Path-style URLs (R2, MinIO) | Required by some providers |
| Plain HTTP (private MinIO only) | Only for a MinIO server on a private network |
Click Test connection, then Save. From then on, every account backup and database backup is uploaded after it finishes.
For the exact endpoint, region and bucket-only key for Wasabi, Amazon S3, Cloudflare R2, Backblaze B2, DigitalOcean Spaces, Google Cloud Storage and MinIO, see S3 storage providers.
Encryption and the recovery key
Copies are encrypted on the server before they are uploaded, with XChaCha20-Poly1305 and a key derived from the panel's recovery key. The storage provider, or anyone who gets the bucket's access key, sees only encrypted data. Encrypted files are split into authenticated chunks, so a truncated or modified file fails to open instead of restoring damaged data.
To see the key, open Backups → Disaster recovery → Show key. Write it down and keep it off the server, for example in a password manager. Without it, nothing in the bucket can be read on another server.
Incremental backups (restic)
Incremental backups are set up by the administrator on the Backups page, in the Incremental backups card:
- Turn on Snapshot every account each night (01:00).
- Choose the Destination: This server (/var/backups), or S3. S3 uses the bucket from Settings → Remote backups, which must be set up first.
- Set the retention: Daily (default 7), Weekly (default 4) and Monthly (default 6).
- Click Show recovery key and store this key as well. The restic repository is encrypted with it.
Each snapshot stores only what changed since the last one, so it is deduplicated, compressed and encrypted. Every Saturday at 05:00, ZoPanel checks the repository structure and reads back 2% of the data. If the check fails, administrators get the Backup failed alert.
Database backups
Open Databases, then Backups for a database:
- Automatic backup: Off, Every hour, Every 6 hours or Every day, with the number of copies to Keep.
- Back up now for a manual copy. The list is read again once the copy is done, and the new copy is marked new.
Every engine is supported: MariaDB and PostgreSQL as gzipped SQL (.sql.gz), MongoDB as a gzipped mongodump archive (.archive.gz), Redis as its keys (.redis.gz). Incremental (restic) snapshots include MariaDB, PostgreSQL and MongoDB databases, not Redis.
When remote backups are on, these copies are also sent to S3, encrypted the same way.
Customers' own schedules and S3 storage
Customers can set up their own schedule on their Backups page, in the Automatic backups card:
- Schedule: daily or weekly, with the Day and Time (server).
- What to include: Website files, Databases, Email.
- Copies on server: 1 to 30 (default 3).
- Copy to my storage: any S3-compatible storage (Amazon S3, Cloudflare R2, Backblaze B2, Wasabi, Google Cloud Storage with HMAC keys), with Copies in storage from 1 to 365.
Customer storage must be a public HTTPS endpoint. Addresses on the server's own network are refused. Test connection checks that the bucket can be written.
App and S3 storage backups
Each App Store app has a Backups card on its website's Docker tab, and the S3 storage component has one on the S3 storage page:
- Back up now archives the whole data folder: the app's
/var/lib/zopanel-apps/<instance>/(including its.envwith keys and secrets), or/var/lib/zopanel-storagewith every bucket. The container is paused for the few seconds of the copy, so the copy is consistent. - Schedule: Off (default), Every day or Every week, with the number of copies to Keep (1 to 60, default 7). Older copies are removed.
- Restore stops the app and replaces its data with the copy. Changes made since then are lost. The current data is kept until the restored app starts, and put back if it does not start.
Archives are kept in /var/backups/zopanel-apps/<instance>/ (S3 storage: /var/backups/zopanel-apps/_storage/), a folder only root can read. An app's archives count in its account's disk space (the S3 storage's belong to no account). Deleting an app together with its data (or uninstalling S3 storage with Also delete all data and buckets) also deletes its backups. Anyone who manages an app can back it up now and see its list; the schedule, Restore and deleting a backup are for administrators (customers see "ask your hosting provider" under the list). A failed scheduled backup sends the Backup failed alert.
These archives stay on the server and are not sent to remote backups. Copy important ones off the server (for example with rclone or scp) and store them encrypted, since they contain the apps' secrets. To use one on a new server, install the same app on the same domain, copy the archive into its /var/backups/zopanel-apps/<instance>/ folder and click Restore. Some apps keep a key in the panel's settings rather than in their data (n8n's encryption key, for example): check the app's guide before moving it. For buckets, an S3 tool with the bucket's key (for example rclone sync) also copies the files to other storage.
Restoring
A whole account
- From a backup on the server: Backups → Restore. Files and databases are overwritten with the backup's contents. Each database goes back into the database of the same name and engine the account has now (one recreated with another engine is skipped, and the log says so). PostgreSQL SQL is run as the account through a role with only the owner's rights, MongoDB is restored by a user limited to that database, and Redis keys are restored only if every key in the file belongs to that database.
- From a file made on any ZoPanel server: Backups → Restore from file. The account, websites and databases are recreated with the same names, users and passwords. Websites or databases that already exist with the same names are refused. PostgreSQL, MongoDB and Redis databases are recreated with a new password (the log says which): set one on the Databases page and update the application's settings. An engine not installed on the new server is skipped.
- From S3: Backups → Disaster recovery → Browse S3, then open server → account and click Restore on a backup. If the account does not exist, it is created. This also works for backups of servers that no longer exist.
Single files, folders and mail
In the Snapshots (incremental) card on the Backups page, choose a snapshot, browse it and click Restore on a file or folder. Files go back in place, and newer files with the same name are replaced. Mail is merged into the mailboxes. Customers can do this themselves for their own account, and they can click Snapshot now before a risky change.
Databases
- In a database's Backups list, click Restore. The current data is backed up first (type before restore), so the restore can be undone. A Redis database is emptied first, then its keys from the backup are put back.
- After any database restore or import, the object cache of the WordPress sites using that database is emptied.
- From a snapshot, a restored database is added to that database's backup list, ready to restore.
Good practice
- Turn on remote backups. Security Center warns when Backups leave the server is not met, and when no backup has succeeded in 48 hours.
- Keep the recovery key and the incremental key outside the server.
- Test a restore on a spare server from time to time. A backup that was never restored is not proven.