Back up a site and set a schedule

A backup archive is a .tar.gz of the site’s htdocs directory plus a dump of its database, written on the hosting’s node. Nothing is backed up on a schedule until you set one: a hosting that no profile or care plan has configured has automatic backups off.

Before you start

You hold the Run backups permission on the site. The built-in roles Owner, Administrator, Operator and Customer have it; Read-only does not.
The node that holds the site has free disk space. A backup is refused up front when the backup volume has less free space than the site’s htdocs size plus 256 MiB.
The hosting is not a reverse proxy. A reverse-proxy hosting has no Backups tab.

Steps

Open Hostings in the sidebar and open the site.
Open the Backups tab.
Click Back up now. You land on the job page, which shows the phases files, database and off-site as they finish. A site without a database skips the database phase. The off-site phase appears only when an off-site target applies to this run.
To schedule backups, expand Schedule and off-site destination… (visible to Administrators and Owners) and set Automatic backups:
- Off — only when I click
- Daily, Weekly or Monthly: a new backup is due 1, 7 or 30 days after the last run.
- Custom — every N days: enter a whole number from 1 to 365 in Every.
Optionally set At to a 24-hour time. The time is the node’s local time. Empty means any time.
Click Save schedule.

How the schedule runs

Each node checks every 5 minutes which of its active sites are due.

Without a time, a site is due as soon as its period has passed since its last attempt. A site that has never run is due on the next check.
With a time, the next backup is due at that time on the day the period lands, counted in calendar days from the day of the last run. A site that has never run takes its first backup at the next occurrence of that time, but only within 2 hours after it. After that window the first backup waits for the same time the next day.
The attempt time is recorded before the backup starts. A backup that fails is tried again after a full period, not on the next check.
Only sites in the active state are backed up. Suspended and trashed sites are skipped.

What a backup run does

Checks free space on the backup volume.
Writes <domain>-<timestamp>.tar.gz to /var/lib/hyperion/backups/local/<system user>/. The archive is made as the site’s own system user, so files that user cannot read are skipped. A file that changes while the archive is written does not fail the backup.
Dumps the database to <domain>-<timestamp>.sql beside it (MariaDB with mariadb-dump, PostgreSQL in custom format with pg_dump -Fc).
Writes <domain>-<timestamp>.manifest.json beside them.
Marks the run ok and records a BLAKE3 fingerprint of the archive.
Copies the files to the off-site targets that apply, if any. See Copy backups off-site.
Applies retention, which deletes old archives. See Set how long backups are kept.

Read the backup list

The Archives card lists the 10 most recent runs.

Column	Meaning
Started	When the run began.
State	ok, failed or running. A before update tag marks the full backup taken before automatic WordPress updates. A site keeps one of these. It is deleted 24 hours after a clean update batch, and kept until replaced when an update failed. See Update WordPress.
Off-site	off-site ✓: the copy was listed back from the remote at the right size. uploaded: the transfer returned success but nobody listed it back. off-site FAILED: the push or its re-check failed. removed off-site: deleted from the FTP target on purpose. A dash: no off-site copy is recorded.
Size	Archive plus database dump.
Archive	The archive file name, or off-site only when the local copy was deleted.

A small fingerprinted tag under Off-site means a content digest was recorded when the archive was made. Hover over it to see the digest.

Check that it worked

A usable backup has all of these:

The State is ok and the Size is plausible for the site.
For a site with a database, a .sql file with the same stem sits beside the archive. Run these on the node:
Terminal window
```
sudo ls -l /var/lib/hyperion/backups/local/<system-user>/ | grep <domain>
```
Expected: a .tar.gz, a .sql and a .manifest.json with the same <domain>-<timestamp> stem.
The archive decompresses completely:
Terminal window
```
sudo gzip -t /var/lib/hyperion/backups/local/<system-user>/<domain>-<timestamp>.tar.gz && echo OK
```
Expected: OK. tar -tzf alone is not enough, because a truncated archive can still list.
For a MariaDB dump, the last lines of the file name the end of the dump:
Terminal window
```
sudo tail -n 2 /var/lib/hyperion/backups/local/<system-user>/<domain>-<timestamp>.sql
```
Expected: a line starting -- Dump completed on. A PostgreSQL dump is binary; sudo -u postgres pg_restore --list <file> lists its contents.
If you use an off-site target, the Off-site column shows off-site ✓.

These checks do not prove the files and dump agree with each other, so keep more than one good backup.

From the command line

sudo hctl backup now example.com

This writes a local copy only. Use the panel for a backup that is also copied off-site.

If it fails

not enough disk space: backup of … needs ~… MiB but only … MiB is free on the backup volume on a failed run: free space on the node or delete old backups, then run the backup again.
The schedule was not saved — "every N days" needs a whole number of days from 1 to 365.: enter a whole number in Every.
The schedule was not saved — the time must be HH:MM (24-hour), or empty for any time.: correct the At field.
The schedule was not saved — the owning node could not be reached: the site’s node is offline. Bring it back and save again.
A row that stays running: a backup of a large site takes minutes. Watch the job under Background jobs. A running backup cannot be deleted.
Off-site copies are not happening for this site. (a warning on the card): the S3 destination the site is pinned to is missing, disabled or lacks its secret key. See Copy backups off-site.