Take and restore snapshots

A snapshot is a restic snapshot of the site’s document root plus a dump of its database. It lives on the site’s node only and is the fast way back after a bad update. It is not a copy that survives losing the server; archives and their off-site copies are for that. Restic stores each chunk once, so thirty snapshots cost little more than one.

Hyperion takes a snapshot before it applies a hosting’s automatic updates (marked before automatic updates, or before a WordPress core update) and whenever you take one by hand (taken by hand).

Before you start

restic is installed on the site’s node. The Hyperion installers install it. The card says so when it is missing.
Snapshots are switched on for the node. They are on unless [snapshots] enabled = false is set in the node’s agent.toml.
What is kept in Settings → Backups is Both — archives for disaster recovery, snapshots for undo or Snapshots only — no scheduled archives, and no off-site copy. With Backup archives only — no snapshots are taken, no new snapshots are taken, but existing ones can still be restored or deleted.
To take or delete snapshots you need the Run backups permission. To restore one you need Restore backups.

Steps

Take a snapshot

Open Hostings, open the site and open the Backups tab.
In the Snapshots card click Snapshot now. A Take snapshot job runs. The first snapshot of a large site reads the whole tree.

The Snapshots card lists Taken, Why, Contains (files + database or files only) and the disk space the site’s snapshots use. A snapshot of a site whose database could not be dumped holds files only.

See what changed

Click What changed on a row. It compares the snapshot with the one before it and shows how many files were added, removed and changed, with a short sample of paths. The oldest snapshot has no such button.

Replace the site with a snapshot

What changes. The site’s document root is replaced by the snapshot’s, not merged with it. Files added since the snapshot are gone from the live site. With database ticked, the database is replaced by the snapshot’s dump too.

What is kept. The current files are moved aside, not deleted, to /home/.hyperion-replaced/<hosting id>-<unix time> (under the node’s home root, /home by default). Nothing deletes that directory for you: delete it yourself once the site is confirmed good. A snapshot of the current files is attempted first and, when it succeeds, appears in the list as before a restore. It is best-effort: it is skipped without an error when restic is unavailable, snapshots are off on the node, or the document root is empty. The current database is not kept, so a database restore cannot be undone from here.

Verify first. Check that the row you pick shows the Taken time you want, and that Contains says files + database if you want the database back. Check What changed against the previous snapshot.

Undo. The job log shows the id of the before a restore snapshot, or says none could be taken. The parked directory is the reliable undo for the files: move it back. When the snapshot exists you can also restore it. If the database import fails, the files are put back automatically and the error says so.

In the row click Restore. Both files and database are ticked. Untick one to restore only the other. A snapshot without a database has no database box. Ticking neither is refused with Nothing was selected to restore — tick the files, the database, or both.
In the dialog click Replace the site.
Follow the snapshot-restore job on the job page. Its log lists whether files and database were restored, the before a restore snapshot id, and where the previous files were left.

The restore needs room for the restored tree and the old tree at once and is refused when the node can tell the disk cannot hold both.

Delete snapshots

Delete on a row removes that snapshot and frees its space. This cannot be undone.
Delete all snapshots removes every snapshot of the site. It asks you to type the domain. Archives and off-site copies are not touched. This cannot be undone.

Both need the Run backups permission. Retention also deletes snapshots; see Set how long backups are kept. A row marked expiring is older than the rule allows and is deleted at the next daily sweep.

Check that it worked

After a restore, the job log shows ✓ files restored and, if you ticked it, ✓ database restored.
Open the site and check it. On the node:
Terminal window
```
sudo ls -ld /home/.hyperion-replaced/*
```
Expected: the directory named in the job log.
After a delete, the row is gone from the Snapshots card.

From the command line

sudo hctl snapshot list example.com
sudo hctl snapshot now example.com
sudo hctl snapshot restore example.com 4f2a91c3

snapshot restore takes --mode all|db|files and names the snapshot of the replaced state in its output.

If it fails

The node that holds this site has no snapshot engine (restic is not installed) (a warning on the card): install restic on that node.
Snapshots are switched off on this site's node: set enabled = true under [snapshots] in the node’s agent.toml, or remove the line.
No snapshot was taken. on a Snapshot now job: the job text lists the three causes (no restic, snapshots switched off, or no document tree). The agent log on that node names which.
snapshot … holds no database dump — restore the files only, or use a backup archive.: untick database.
snapshot … does not contain … — it may belong to a site whose document root has since moved: use an archive instead.
… WARNING: the files were already replaced and could not be put back. The previous ones are at …: the database import failed and the automatic roll-back failed. Move the directory named in the message back into place.

Update WordPress, plugins and themes