Backup and site migration

by Gisle Hannemyr

This chapter discusses various methods for creating a backup of a Grav website, and how to migrate a complete site to a new location. It also discusses how to use the CLI to mirror all the files that make up a Grav website to another web server.

Table of contents

Grav plugins mentioned in this chapter: None.

Introduction

[This is still the ghost of the chapter fror D7. It requires cleaning up.]

Whether you are hosting your site yourself, or you use a hosting service, you need to have a robust backup system in place. If you are hosting your site yourself, there will be nobody else that will take care of backups. Most hosting services offer backup as part of the standard plan, and you may opt in on this provided you trust your provider. This chapter only describes how to set up and manage your own backups.

Something known as the “3-2-1” backup practice is recommended. This is an easy-to-remember acronym for a keeping at least three (3) copies of your files, store two (2) backup copies on different storage media, with one (1) of them located offsite. A common approach is to have the following three backup locations:

  1. Production files.
  2. Local backup of the production files.
  3. Offsite archive of timestamped copies of the production files.

The “3-2-1” backup practice ensures that a local copy is available for fast roll-back for non-mechanical failures (e.g. a hacker compromises or a bug corrupts the website), while an offsite backup ensures that the data does not disappear if your producation location breaks down mechanically, e.g. by fire or flood, so that all data stored on that location are lost.

Obviously, the more backups you have, the less chance you have to lose all of them at once. But, the “3-2-1” backup practice is a well-proven and cost-efficient way of securing the data against loss.

A working Grav website is made up of the following components:

To be able to restore a site from backup, all components must be recreated from a saved copy, or the original copies must remain in place.

To migrate a site to another web server (physical or virtual) the components that make up the source website must be copied to the target website and put together to mirror the configuration of the source website.

This chapter will describe how to make a backup of a Grav website and restore that at the same locaton, and how to migrate a Grav website to another location. It will focus on the use of some CLI tools for these tasks.

Backing up the files

To create a backup of the files, you may use the CLI and tar to bundle all the files into a tarball, and copy that to a backup server. For example, you may do the following (assuming Grav root is /var/www/html):

$ cd /var/www
$ tar -czf allfiles.tar.gz html/
$ scp allfiles.tar.gz user@example.com:/var/backup

However. the non-asset files on a Grav site consists of the Grav core, contributed exensions (plugins and themes), custom extensions, libararies and translations. On a production site, this is usually stable, and only changes when one of the components is updated. All these components can be restored by downloading a fresh copy from their source.

For a small production site running plain vanilla Grav, it is usually suffiscient to keep a record of all files that make up the site and where they are located. You can do this with the following CLI-command to record the entire file tree (provided your Grav root is /var/www/html):

$ tree /var/www/html > tree.txt
$ scp tree.txt user@example.com:/var/backup

The media assets are files that are uploaded by the site's users. To back up these files, you may mirror them on a backup server. To keep the backup small, you may want to flush the image styles cache prior to creating the tarball:

$ cd /var/www/html/sites/default
$ drush image-flush
$ tar -czf assets.tar.gz files/
$ scp assets.tar.gz user@example.com:/var/backup

Or, to save even more space, you may only back up the directories containing non-cached media assets (analyse your assets to determine what those are).

To restore the site, download fresh copies of all non-asset files from their source and all media assets from backup, then use the tree command again to produce tree2.txt, and then use the diff CLI-command to verify that you've been reproduced the exact same files at the destination site in the same location as the original.

Migrating a site

To migrate a site, you need to perform the following steps:

  1. Prepare for migration.
  2. Transfer all the files that make up the source site to the target site, and restore them to the same location in the file tree below the Grav root as they had on the source site.

Perparing for migration

To prepare a site for migration, you should first clean the environment of any excess baggage. Revert to the default theme and language, upgrade everything to the latest stable version, and disable, uninstall and delete anything you no longer need. Here is a checklist of things to do:

  1. Put the site in maintenance mode to prevent it being changed by users.
  2. Revert to the default theme (Bartik).
  3. Revert to the default language (English).
  4. Disable, uninstall and delete all plugins that you do not use.
  5. Upgrade the core and contributed projects to their latest stable version.
  6. Delete all inactive users.
  7. Delete all nodes that are no longer relevant.
  8. Delete content types that are no longer relevant.
  9. Delete orphan files.
  10. Flush the image cache (drush image-flush).

Migrate the files

If both the source and the target is on the same file system, just recursively copy the Grav root from one vhost root to another. For example (assuming the Grav root of the source is /var/www/source.com/html and the Grav root of the destination is /var/www/destination.com/html):

$ cp -R /var/www/source.com/html /var/www/destination.com/

If both the source and the target is on different file systems, the CLI with the command rsync will copy all files in the file tree root given as an argument. Provided you are logged in on the mirror server (i.e. the backup or the target server), the following rsync command will make a copy of all the files below the Grav root in the source server (assuming the Grav root is /var/www/html, and that all italics are replaced with relevant strings):

$ rsync -r user@example.com:/var/www/html /var/www

If rsync is not available (many sites have firewall-settings that block ssh), you can migrate the files by first creating a backup of the files by using one of the methods described above.

After copying the tarball to the target destination, unpack it to the new Grav root. For example:

$ cd /var/www
$ tar -xvzf allfiles.tar.gz

You may need to change the name of the topmost directory if this has not the same name as was configured for the source web server.

Finalizing migration

After everything has been migrated to the target site, you may turn on the custom theme and additional languages, the clear all caches. Your destination site should now be an exact copy of the source site. Navigate to Reports » Status report to verify that everything is OK (and fix the errors if it is not).

When everything is OK, take the target site out of maintenance mode and start using it.

Merging sites

[TBA]

Final word

If you set up scheduled backups to be stored on the local file system for the site you are backing up, you need to arrange for having it copied (by scp or similar) offsite. How to write the scripts to automate this process is left as an exercise to the reader.

noteBackup files often contain personal data. Make sure your backup-files are not accessible to outsiders. If you're backing up to the server, you should test to see if your backup files are publicly accessible. Storing backup files on a public file system is a very common cause of information disclosure.

Last update: 2020-05-09.