Support

Documentation

This documentation page is for Joomla! 3.x

This documentation page does not apply to our software versions for Joomla! 4.0 and later versions. If you are not using Joomla 3 please consult the documentation index to find and read the correct version of the documentation.

Chapter 5. Restoring backups and general guidelines

Table of Contents

General guidelines for backing up and restoring your site
Guidelines for storing your backups remotely / "cloud backup"
Overview of the backup restoration procedure
Extracting your backup archives
Using the integrated restoration feature (most common)
Using Akeeba Kickstart
Using third party software
ANGIE: Akeeba Backup's restoration scripts
Common instructions for all ANGIE installers
The session fix page
The password page
The main page
The database restoration page
Off-site directories restoration page
The “Finished” page
ANGIE for Joomla!
First page
Site setup page
ANGIE for Miscellaneous PHP Applications
First page
Site setup page
Restoration (ANGIE) troubleshooting
ANGIE reports that the session write path and the installation directory is unreadable
PHP errors , warnings, notices or a blank page upon accessing ANGIE / restoration
Some required or optional settings are red in ANGIE's first page
I can't restore my database, or receive AJAX Error, timeout or other errors while restoring my database with ANGIE
Error message mentioning utf8mb4_0900_ai_ci when restoring on MariaDB
I restored my database but can't proceed to the next page of ANGIE
My configuration.php wasn't written to disk after ANGIE ran
Any other ANGIE error
Troubleshooting restored sites
Common issues on restored sites and how to solve them
Common issues on restored sites due to PHP incompatibilities between the source and target server
When updating the restored site, the original site changes as well (Entangled web sites)
Clicking on a link on the restored site takes me to the original site (link migration issues)
Issues arising from your computer configuration, browser, ISP, antivirus and firewall incompatibilities
Unorthodox: the emergency restoration procedure

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.

Multipart backup archives. Some backup archives may consist of more than one files. These are called multipart backup archives. You MUST download all part files to have a backup archive set which can be used to extract all files and restore a site. All files have the same base name, for example site-www.example.com-20220925-105300-abcdef012345, but different extensions. JPA archives have the extensions .jpa, .j01, .j02, …; JPS archives have the extensions .jps, .j01, .j02, …; ZIP archives have the extensions .zip, .z01, .z02, … The part files of a multipart backup archive are NOT separate archives; you cannot extract its one of them individually. The are all parts of the same archive and they all need to be present for the archive to be able to be extracted. The order of the parts is .j01, .j02, …, .jpa for JPA archives; .j01, .j02, …, .jps for JPS archives; and .z01, .z02, …, .zip for ZIP archives. That is to say, the numbered part files come first in the numeric order defined by their extension, the file with the .jpa, .jps or .zip extension comes last. You can extract multipart archives using the integrated restoration but also Akeeba Kickstart Core, our free of charge archive extraction tool. It can run on a web server — even a local web server created with MAMP, WAMPserver, XAMPP etc — or, for expert users, on the command line.

Akeeba Backup archives are self-contained. The backup archive contains a copy of your site's files, an export of its database data and the restoration script to put everything together. This is very different to most other backup software in that the restoration script is inside the backup itself, not a separate thing you need to install. The only thing you need to do before restoring a backup is extract the backup archive. This can be done with Akeeba Kickstart (single file web application), Akeeba UNiTE (automatic site restoration running under the CLI) etc.

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.

You DO NOT need to install Joomla! before restoring a backup. As explained above, an Akeeba Backup archive contains your entire site and the restoration script required to restore it. You do not need to have a functional site to restore a backup. The whole point of Akeeba Backup is restoring a backup when the site is no longer functional. Moreover, we recommend NOT installing Joomla! before restoring a backup because of the point described below about mixing different versions of Joomla!.

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 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.

Make sure you have a database. Even though Akeeba Backup's restoration script can try to create a database for you this WILL NOT work on most database servers for security reasons. Creating a database requires database server administrator (root) privileges which you typically do not have and, even if you do, should not use when restoring a site to a live server. Instead, create a database for your site in advance. You will also need to create a database user and give it the correct privileges as described in our troubleshooter.

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!

The restored site is a fully functional clone of your original site. There is no functional difference between a restored site and one you built from scratch. This means that you can always backup the restored site and then restore that new backup on top of the original site. This makes Akeeba Backup ideal for live-to-development and development-to-live site transfers. If you are an advanced user such as a busy web agency do note that the process can be fully automated using Akeeba UNiTE: it can take a backup remotely, download it and restore it.