Support

Documentation

Chapter 5. Restoring backups and general guidelines

We kindly request our users to read the general guidelines before filing a support ticket, a bug report or giving up. Most frustrating and "inexplicable" problems end up being a simple case of misunderstanding how things work, making the wrong configuration choice or a server issue which can typically be resolved by asking your host nicely. The guidelines below aim to prevent most of the common issues or, if prevention is unlikely, at least help you identify the root cause and tell you how to fix it.

General guidelines for backing up and restoring your site

Restoring sites with Akeeba Backup is easy. Sometimes it may even be too easy which makes you prone to making obvious mistakes due to the implied complacency of using third party software to restore your site. In the following paragraphs we explain how to avoid the most common mistakes. This is a long read but we recommend that you read and understand it. We will not accept any "bug" reports about these issues which are, ultimately, user errors. If you need clarifications about any of these issues, however, do feel free to ask us (and be specific about what you didn't understand). We will be happy to help you better understand the issue.

Make sure you have backups before you need to restore your site. Over the years we've come across many people who were furious that having installed, but not having used, our backup software didn't help them when their site got destroyed. Don't be that person. Take frequent backups of your site, at the very least before updating Joomla! and its extensions and after making any substantial change to your site. It's dull, it's boring, it's a chore, it will save your life one day. Always keep at least one copy (ideally: three copies) of your backups outside of your site and ideally outside of your computer too. What is the point of having your backups stored on your site's server when the server's disk crashes or the hosting company goes bankrupt?

Test your backups periodically. Maybe you excluded a database table you didn't mean to. Maybe a folder was unreadable but you ignored the warning. Maybe the FTP program you are using to download your backups is broken. Maybe you accidentally set the temp-directory or logs file directory of your site to your site's root or another important system folder, ending up excluding it automatically in the process. Maybe there was a bug in the version of Akeeba Backup you were using, it created a corrupt archive and you didn't update to the next version that fixed it (it happens once every 3-4 years, we usually fix the issue within 24 hours). No matter what happened, a corrupt backup can ruin your day. Test your backups periodically to make sure that they actually work.

Restoring a backup overwrites the entire site (Joomla! installation). It cannot be used to transfer content between different Joomla! installations. An Akeeba Backup archive contains your entire site, files and database contents. Restoring a backup will overwrite the files and database tables that have the same name as those included in the backup. As a result it cannot be used to transfer content (e.g. articles) between two different Joomla! installations. It will transfer the entire Joomla! installation instead.

Restoring a backup does NOT delete files on your site which don't exist in your backup. If a file exists on the site you are restoring to but not inside the backup archive itself it will not be overwritten. This is important in two cases. First, when you are restoring a backup after your site is hacked (unhacking a site). The hacker may have left behind files which can be used to re-hack your site. These files will not be deleted automatically. Use a component, such as Admin Tools Professionals with its PHP File Change Scanner, or a third party service such as myJoomla.com to detect and remove such files. Furthermore, if you are trying to replace a site with a new one. If the old site is based on an older version of Joomla!, a different CMS (e.g. WordPress), is a static site or had different extensions / templates installed these files will be left behind. In both of these uses cases you should take a copy of your site's files, then delete all files and folders, create a new database and finally restore the backup.

Make sure you are backing up only the files that belong to the site you want to back up. This is very important when you are backing up a site in the root of your domain but you have additional sites in subdirectories (or subdomains whose root directory is a subdirectory of your main site). Akeeba Backup does NOT assign meaning to your directory names! It does not know that the directory old_site has a copy of your site from two years ago or that the folder gju4rl has the files for a subdomain you use to share files with your cousin who lives in another country. Akeeba Backup will backup all files and folders under the root of your site unless you tell it otherwise with the Files and Directories Exclusion feature. In any other case restoring your main site would overwrite the files of all the sites in subdirectories under your main site's root!

Make sure you are backing up only the database tables that belong to the site you want to back up. This is very important when you are backing up a site that shares a database with another site. Akeeba Backup does NOT assign meaning to the prefix used by your database tables. All tables in the database used by your site will be backed up regardless of their database prefix. If you use the same database for the tables of other sites, e.g. sites installed in subdorectories or subdomains on the same hosting account, you MUST exclude them manually with the Database Tables Exclusion feature. Otherwise restoring your site would overwrite the database of all of the other sites sharing the same database.

Keep copies of your backup archives outside of your site. The reason is simple: human error. If you mess up the restoration and, at the same time, somehow delete your only backup archive you are in deep trouble. Always keep several copies of your backup archives before doing a restoration. We recommend having at least THREE copies: on your computer, on a cloud storage provider (e.g. Dropbox, OneDrive, Google Drive, ...) and on a USB stick you keep in a sealed envelope in your desk's drawer. You can never have too many copies of your backups - but you can have too few!

Always practice the restoration on a test server / subdomain before doing it on your live site. Do you know why the military has so many drills? By repeating the same task over and over they get to perform it near perfectly, every single time, without thinking - even when bullets are flying around them. You don't want to start learning how to restore backups when your site is down. At that point you want your site restored, pronto. That's why you should practice restoring backups before you need to restore them. Practice on a test server, e.g. a MAMP, WAMPServer or XAMPP installation on your computer, or a subdomain on a server under your control. Once you have done this a few times you can restore any site, anywhere, without much thinking and without mistakes.

Do not restore in a subdirectory of your main site. For example, if your site's root is in public_html do not restore to public_html/dev. The reason is that the .htaccess files, which tell Apache (your web server) how to server your site, cascade. That is, Apache will read all .htaccess files in all folders leading to the one hosting your site's index.php file. This will cause problems with the restored site which you will experience as 404, 403 and 500 error messages or blank pages. These have nothing to do with our software and / or the restoration. It's how your web server works. Use a subdomain instead.

If you are restoring on a subdomain, make sure that the subdomain's root directory is NOT a subdirectory of your main site. This is the same as the previous paragraph, really. Most hosting control panel software default to using a subdirectory of your site's root when creating a subdomain. For example, if your site is www.example.com and its root is public_html if you create the subdomain dev.example.com your hosting control panel will put its root in public_html/dev. Therefore you will have the problem we described above. In this case ask your host what is the best way to create a root folder for the subdomain next to public_html, not inside it.

Try restoring to as close a PHP version as possible. Not all third party extensions support all PHP versions. If your site was running on PHP 5.6 and you try to restore it on a server running PHP 5.3 or PHP 7.1 your site may break. This has, again, nothing to do with Akeeba Backup. Upholding the minimum / maximum PHP version requirements of the software running on your site is your responsibility. We have no way of knowing that information. All we can do is print out the PHP version of the site you backed up and the site you are restoring to during restoration. Everything else is up to you.

Don't try to restore to a different database technology. If your site runs on MySQL don't try to restore it on a server that only supports PostgreSQL or Microsoft SQL Server. Even though Joomla! 3 supports all of these database technologies they are incompatible with each other and you cannot transfer data between them. You can only restore a site on the same database technology it was backed up on. Clarification: MySQL, Percona and MariaDB are all using the same database technology, collectively called "MySQL". While you can a site between these different MySQL-type database servers we recommend against it. Subtle differences between them may cause restoration errors in some cases. In the few cases we can prevent that, we have added the necessary workarounds. There are some cases we can do nothing about. If you get a database restoration issue please check if you're trying to restore to a different MySQL-like database server than the one you backed up from.

Do not try to overwrite one Joomla! version family with a different one. Overwriting a major version with another (e.g. restoring a backup taken on Joomla! 3.7 on top of a site running Joomla! 2.5 or vice versa) or between different minor versions (e.g. restoring a backup taken on Joomla! 3.7 on top of a site running Joomla! 3.6 or vice versa) will NOT work. Joomla! moves files around between minor and major versions. Since the backup does not delete files not present in the backup archive this will end up with Joomla! being "confused" and malfunctioning. In these cases you should delete the existing files and folders (except, perhaps, user generated content) before restoring the backup. You can safely restore a sub-minor (path-level) version on top of another. For example, you can safely restore a Joomla! 3.7.5 site on top of a Joomla! 3.7.3 site or vice versa.

Pay attention when restoring to a different domain, subdomain or folder: you will need to enter the domain name, directory and database connection information where you are restoring to. If you don't pay attention you may overwrite a site you didn't intend to touch!