Restore a site from a backup

Restoring writes a backup over the live hosting. Pick the method by where the backup is and what you want to overwrite.

You have	Use	Overwrites
A row in the Archives list with a local archive	Restore	Files from the archive over the site, and the database
The same row, database only	DB only	The database only
A row marked off-site only	Restore from off-site or Files only	Same as above, after downloading from the FTP target
A file on your computer	Upload & restore	Files only
A path on the node	From an archive already on the server	Files, and the database when a .sql sits beside the archive
An archive, into a different domain, for a site that is not WordPress	Into a new domain	Creates a new hosting. On WordPress sites it also rewrites URLs in the original’s database, so do not use it there
A snapshot	See Take and restore snapshots	Replaces the whole document root

Before you start

• You hold the Restore backups permission on the site (Owner, Administrator, Operator and Customer roles). The server-path method needs an Administrator or Owner. Into a new domain needs an Administrator or Owner and the Migrate / clone hostings permission.
• Decide what you are willing to lose. An archive restore does not take a safety backup first.
• If the site matters, take a backup now so the current state can be restored again. See Back up a site and set a schedule.
• Consider turning on Maintenance mode (hosting page, Settings & limits tab, Availability & speed). It answers every request with a 503 page, and the panel describes it as meant for deploys and database restores.

What a restore overwrites

Before you restore over a live site

Files. The archive is extracted over /home/<system user>/<domain>/ as the htdocs directory. Files with the same path are replaced by the archive’s version. Files that were added after the backup are left in place, they are not deleted. Use a snapshot restore if you need the whole tree replaced.

Database. The .sql dump beside the archive is replayed into the site’s own database as the site’s database user. The dump drops and re-creates each table it contains, so every row changed since the backup in those tables is lost.

Ownership. After extraction Hyperion repairs ownership and permissions of the site tree and purges the page cache.

Not touched. Logs, nginx vhost, PHP settings, certificates, cron entries, FTP logins and the database user’s password.

Verify a usable backup first. Open the Backups tab and check that the row you restore shows ok, a plausible Size and, for a database site, a .sql beside the archive. The checks are in Back up a site and set a schedule.

Undo. There is no undo. To keep the way back, take Back up now before you restore. An archive restore does not keep the files it overwrites.

Restore a listed archive

1. Open Hostings, open the site and open the Backups tab.
2. Find the row in Archives. The row must be in state ok and show an archive file name.
3. Click Restore to restore files and database, or DB only to restore only the database (shown for sites with a database). In the dialog click Restore or Restore database.
4. Follow the Restore backup job on the job page until it shows Done.

A member of the archive that would escape the site directory is refused, and file ownership and modes from the archive are not kept: ownership is set to the site’s user afterwards.

Restore from the off-site FTP copy

A row whose local copy was deleted shows off-site only.

1. In that row click Restore from off-site (files and database) or Files only (shown for sites with a database).
2. Confirm Download and restore.
3. The job downloads the database dump first, then the archive, then restores. It refuses to continue when the dump is missing on the remote and you asked for the database. The downloaded copy is deleted afterwards because it is still on the remote.

You can also use Off-site copies at the bottom of the tab, which lists what the remote server itself holds. Pick files + database or files only in the row and click Restore. Restoring only the database from an off-site copy is not offered.

S3 copies cannot be restored from the panel. See Copy backups off-site for the manual route.

Restore an uploaded archive

1. Open Other ways to restore at the bottom of the tab.
2. Under From a .tar.gz upload, choose the file in Archive file. It must end in .tar.gz and be at most 2 GiB.
3. Click Upload & restore and confirm.

The file is saved under /var/lib/hyperion/backups/incoming/<hosting id>/ and restored. Only files are restored. The database is restored only if a .sql with the same stem sits beside the saved file, which an upload never provides, so it is not touched. This works only for sites on the master. For a site on another node the panel answers that restoring from an uploaded archive works only for sites on the master and changes nothing.

Restore an archive already on the server

1. Under Other ways to restore, find From an archive already on the server (Administrators and Owners).
2. In Archive path enter the full path of an archive on the site’s node, for example /var/lib/hyperion/backups/local/<system-user>/example.com-<timestamp>.tar.gz.
3. Click Restore and confirm.

The path must be under /var/lib/hyperion/backups/local, /var/lib/hyperion/backups/incoming, /var/lib/hyperion/migration or /var/lib/hyperion/migration-incoming. When a .sql with the same stem sits beside the archive and the site has a database, the database is restored too. A user below Administrator can restore only archives listed on the site’s own Archives card; otherwise the panel answers That archive is not one of this site's backups.

Restore into a new domain

This creates a new hosting from an archive, using the original’s PHP version, database engine and kind. The restore into the new hosting is separate from the original’s files, but see the warning for WordPress.

Do not use this method on WordPress sites

The restored files keep the wp-config.php they were saved with, so the new site’s wp-config.php names the original’s database. Hyperion then runs wp search-replace from the original’s address to the new one through that file. It therefore rewrites the URLs in the original site’s database, and the original starts redirecting and linking to the new domain. The rewrite is best-effort: a failure is not reported, and the restore returns without telling you which database it touched. Hyperion does not rewrite database credentials inside restored files.

To duplicate a live WordPress site, use Move / copy instead, which points the copy at its own database. See Move or copy a site.

If you already did it, repair in this order:

1. Open the original site at once and check that its address is its own. The sooner you repair, the fewer visitors are sent to the wrong domain.

2. Undo the rewrite in the original’s database. On the original’s node, as the original’s system user, with the original’s own wp-config.php still in place:

   sudo -H -u <original-system-user> /usr/local/bin/wp --path=/home/<original-system-user>/<original-domain>/htdocs search-replace '//<new-domain>' '//<original-domain>' --all-tables --skip-columns=guid

   Expected: a table of replacements. Reload the original.

3. Open the new site’s Overview tab and read the Database card (Name and User). The password is never displayed. Expand Reset the database password… on that card, enter a new password of at least 12 characters (or click Generate), and click Reset password. The panel updates the database user and its stored secret. Edit the new site’s wp-config.php so DB_NAME, DB_USER and DB_PASSWORD match the Name, User and the password you just set.

4. Run the rewrite for the new site against its own database:

   sudo -H -u <new-system-user> /usr/local/bin/wp --path=/home/<new-system-user>/<new-domain>/htdocs search-replace '//<original-domain>' '//<new-domain>' --all-tables --skip-columns=guid

Steps for a site that is not WordPress

1. Open Hostings, open the original site and open the Backups tab.
2. Expand Other ways to restore and find Into a new domain.
3. In Archive path enter the archive’s full path on the site’s node, for example /var/lib/hyperion/backups/local/<system-user>/<domain>-<timestamp>.tar.gz.
4. In New domain enter the new site’s domain, for example copy.example.com. It must differ from the original.
5. Click Create & restore and confirm.

Hyperion creates the hosting and restores files and database into it. The restored files keep their own configuration, so open any application config that names a database (for example .env) and make it match the Database card of the new site’s Overview tab before you use the site.

On success you land on the new hosting. If the restore step fails, the half-created hosting is deleted so you can try again.

Check that it worked

1. For Restore, DB only, Restore from off-site and Files only, the job on Background jobs ends Done. A restore job cannot be retried; start it again from the Backups tab. Upload & restore and Into a new domain are not jobs: the page waits, then returns to the site (or the new site) with a result or a Restore failed: message.

2. Open the site and check the pages and data you expect.

3. Check files on the node:

   sudo ls -ld /home/<system-user>/<domain>/htdocs

   Expected: owned by <system-user>.

4. For a database restore, compare a known row or table count with what you expect, for example in phpMyAdmin.

From the command line

sudo hctl backup list example.com
sudo hctl backup restore example.com 42 --mode files --yes

--mode takes all, db or files. The backup must still have a local archive.

If it fails

• Restore failed: followed by archive not readable: …: the archive path does not exist on the node. Check the spelling and that the file was not deleted.
• archive … is not under an allowed backup root: move the file under one of the roots listed above.
• this backup is being removed from local disk right now (it is verified off-site) — restore it from the site's Off-site panel instead: the local copy is being deleted by the local-copy setting. Use Restore from off-site.
• db-only restore requested but this backup has no .sql dump: the site had no database when the backup ran. Restore files only.
• the backup's database dump disappeared while the files were being restored: the files were put back but the database was not. Restore the database again from this backup’s off-site copy.
• A database-only restore from the off-site copy is not supported.: restore from the off-site copy with files and database, or download the dump and use the server-path method.
• Restoring into a new domain from a server path needs an admin. or Enter a new domain for the restored copy.: use an Administrator or Owner account, and fill in New domain.
• archive must be a .tar.gz file: the uploaded file name does not end in .tar.gz.

Related

• Create a website
• Issue an HTTPS certificate
• HTTP API reference