Support

Documentation

Migrating from old versions of Akeeba Backup

Akeeba Backup has been around since the early days of Joomla 1.0 all the way back in 2006. It has gone through several rewrites, the latest one being in mid-2021 with Akeeba Backup for Joomla version 9. If your site already had an older version of Akeeba Backup installed you will need to take some easy, manual steps to migrate to the new version.

First, make sure that the old version already installed is in the 7.x or 8.x version range. Go to your site's backend and click on System from the side menu. From the Manage pane select Extensions. Search for Akeeba Backup package. If the version number listed there begins with 6 or a lower number you will need to upgrade this to Akeeba Backup 8. Go to our site, download the latest version of Akeeba Backup 8 and install it. Then download and install Akeeba Backup 9 or later, even if you had previously installed it. This last step is VERY important.

From Joomla's sidebar menu click on Components, Akeeba Backup for Joomla!™, Control Panel. Towards the top of page, above the configuration and action controls, you will see an area titled "Migrate your settings from an older Akeeba Backup version". Click on the Migrate settings button and follow the instructions on your screen (essentially, click a button). This will migrate your settings from the old version of Akeeba Backup to the new one.

You can now uninstall the old version of Akeeba Backup. Go to your site's backend and click on System from the side menu. From the Manage pane select Extensions. Search for Akeeba Backup package. Select it, making sure its version number starts with 7 or 8. Then click on Uninstall from the toolbar.

Caveats

The migration will copy over your component settings, Akeeba Backup profiles and backup history. It will also copy the backup archives stored in the default backup output directory of Akeeba Backup 8 and earlier (administrator/components/com_akeeba/backup) to the new default backup output directory (administrator/components/com_akeebabackup/backup).

The migration will NOT copy backup archives from non-default backup output directories created inside the old Akeeba Backup component directory. That is to say, any backup archive inside a subdirectory of administrator/components/com_akeeba (other than administrator/components/com_akeeba/backup), components/com_akeeba or media/com_akeeba WILL NOT be copied over. You need to download these backup archives PRIOR to uninstalling the old Akeeba Backup version or they will be forever lost. We do not accept any responsibility for data loss resulting from your failure to heed this warning.

CRON scripts

If you were using the akeeba-backup.php, akeeba-altbackup.php, akeeba-check-failed.php or akeeba-altcheck-failed.php scripts please note that they have been removed and replaced by commands for the Joomla! CLI application. You will need to edit your CRON jobs and make the following replacements:

  • akeeba-backup.php to joomla.php akeeba:backup:take

  • akeeba-altbackup.php to joomla.php akeeba:backup:alternate

  • akeeba-check-failed.php to joomla.php akeeba:backup:check

  • akeeba-altcheck-failed.php to joomla.php akeeba:backup:alternate_check

For example, if your CRON command line was

/usr/local/bin/php-cli /home/mysite/cli/akeeba-backup.php --profile=2 1>/dev/null 2>/dev/null

you need to change it so that it now reads

/usr/local/bin/php-cli /home/mysite/cli/joomla.php akeeba:backup:take --profile=2 1>/dev/null 2>/dev/null

You also need to make sure that the plugin Command – Akeeba Backup is published on your site. This plugin is published by default when you install Akeeba Backup for Joomla version 9 or later for the first time.

Please note that the joomla.php application is part of Joomla itself. We do not have control over it. If you get an error before the Akeeba Backup command produces any output the problem lies with Joomla, not our software. Also note that unlike our old CLI scripts, Joomla's CLI application will NOT run with PHP-CGI binaries. It will simply throw an error. Please do not report this as a bug to us, report it to the Joomla project who's responsible for this code and can actually fix it.

Dark Mode

Unlike Akeeba Backup 7 and 8 we no longer include Dark Mode CSS. This is intentional as we are no longer using our own CSS files; we use the Bootstrap CSS which is included with Joomla itself. This means that if you use a dark themed administrator template or a dark mode plugin for the default administrator template our software will also display in the same dark theme as the rest of your site.

Why is a migration necessary?

Akeeba Backup 3.x to 8.x inclusive had the component name com_akeeba, therefore their files were stored in the administrator/components/com_akeeba and components/com_akeeba folders on your site. Its tables had the _ak_ prefix.

During the first two major versions (1.x and 2.x) Akeeba Backup was called JoomlaPack. Since it was compatible with Joomla 1.0 which did not have an extension framework per se they were simply a bunch of PHP scripts with some Joomla binding thrown together. JoomlaPack 2.2 was the first version using Joomla 1.5's MVC. In version 3.0 the component was renamed to Akeeba Backup. Akeeba Backup 3.0 to 3.4 were based on Joomla 1.5's core MVC API. Akeeba Backup 3.5.0 and later were based on our FOF framework (version 1.x, 2.x, 3.x or 4.x of the FOF framework, to make matters more complicated).

The fact that all of these versions of our component had the same component folder name but entirely different internal architectures meant that updates from one version to the next were complicated and error-prone. It was a necessary evil since Joomla 1.5, 1.6, 1.7, 2.5 and 3.x had a very old core MVC API which was unsuitable for writing and efficiently maintaining complex extensions. As a result we had to maintain our own framework and go through complicated extension updates. Even though that was time consuming and potentially error-prone on updates it was less problematic than using the outdated core MVC API.

Starting with Joomla 4.0 the core MVC API includes many of the features we had introduced in FOF. Moreover, bumping the minimum PHP version support to 7.2 in Joomla 4.0 means that the few features we are missing can easily be implemented with minimal amounts of reusable code, called Traits. As a result we decided to discontinue our own framework and use the core MVC API again.

However, this meant that trying to upgrade from Akeeba Backup 8.x and earlier would be very complicated if we kept the same component name due to the nature of the Akeeba Backup component. We needed to use a different component name. We decided to use com_akeebabackup since this addressed another long standing issue: com_akeeba was a misnomer. Akeeba Ltd is the name of our company, our extension is Akeeba Backup, not Akeeba. The original component name comes from a time when we only had one extension so it made sense to call it com_akeeba.

The other problem we had to address was that using the core Joomla MVC API makes it hard to update the database tables if they were created without using the core Joomla extensions installer to begin with, as was the case with Akeeba Backup 4.0 to 8.x. If you were to update from Akeeba Backup 7 or earlier to Akeeba Backup 9 the updated extension would fail to work properly because the database tables wouldn't be updated correctly. Therefore we had to use a different table prefix, _akeebabackup_ which is good practice as well: the table prefix should ideally follow the component name.

These two changes meant that a migration is required from older versions of Akeeba Backup to Akeeba Backup 9 and later. Ideally we'd like to do that when you install the new version of our extension. However, due to limitations of the Joomla extensions installer and updater we could not guarantee there would be enough time available to do that without risking a PHP timeout. Hence the need to do a manual migration. The migration is required exactly once.