Forgot your username?             Forgot your password?

Updating Joomla!

Arguably, one of the most basic site maintenance operations which has a strong impact on security is keeping your Joomla! installation up to date. This used to be a tedious job: you had to note which Joomla! version you're using then go to http://joomla.org/download.html to find out the latest version and compare them. If there was an update, you had to scour the lengthy download page for the update package, extract it locally, upload all the files through FTP and check that everything was working properly. Multiplied by dozens of sites managed by a single site builder this can soon amount into a maintenance nightmare. Not any more.

Admin Tools' Joomla! Core update feature allows for automation of this tedious procedure. Not only does it detect the latest version and does the version comparison for you, but it also allows you to backup (optional, available only if Akeeba Backup 3.1 or later is installed) and then upgrade your core installation with a single click. If you believe that your core files have been compromised, you can always overwrite them with a fresh copy again with our easy-to-use one-click process.

[Important]Important

Admin Tools has to be able to contact joomlacode.org for this feature to work. If it throws an error telling you that you have to upgrade Joomla! manually, please contact your host and ask them to open port 80 connections to joomlacode.org on their firewall. Also ensure that your server either has the PHP curl module installed and enabled (preferred) or allows using the fopen() URL wrappers. If you are unsure, ask your host.

When you launch the Joomla! Core Update tool of Admin Tools you are presented with a page like this:

In this example, Admin Tools detected that the site is running on Joomla! 1.5.15 and the latest release is 1.5.20. It gives us two options:

  • Upgrade to X.Y.Z. This will download and install the "Stable Patch" package which contains only the files changed between the installed and latest release. This is the recommended approach to upgrade an existing site.

  • Reinstall X.Y.Z. This will download and install the full installation package of the latest release, overwriting all Joomla! core files. This is not recommended, unless you have a strong indication that something bad happened to your Joomla! core files, e.g. files missing or have a suspicion of a hacked site. In the latter case, reinstalling the core files is not enough; you'll also need a security audit of your site.

Obviously, if there is no update available -i.e. you already have the latest version- only the Reinstall button will be visible.

[Important]Important

Admin Tools is caching the update information for 8-24 hours in order to avoid looking all the time for updates, slowing your site to a crawl. As a result you may end up with out of date information during the first few hours since a new Joomla! version. This is normal and is not a bug. The only solution to that would involve making your site really dead slow, to the point of being unusable. For your information, Joomla!'s own core and extensions updaters do the same thing: they cache the update information for several hours and exactly for the same reasons. If you want to update your site a.s.a.p. just click on the Reload this information from the server button in Admin Tools. This will instruct Admin Tools to invalidate its cache and refresh the update information from the joomlacode.org server, allowing to perform the update.

[Warning]Warning

Joomla! releases are divided in LTS and STS. LTS releases are those version families which end in .5, e.g. 1.5, 2.5, 3.5, 4.5 and so on. STS releases are those version families ending in any other number, e.g. 1.6, 1.7, 3.0, 3.1, 3.2, 4.0 and so on. LTS are the really stable releases, intended for live sites. They are supported for 18 to 24 months since their release. STS releases are "testing" releases, to be used by developers and people who want to experiment with new features. They are prone to breaking and changing and are supported for only 6 months since their release. We strongly advise AGAINST upgrading from an LTS to an STS release (e.g. 2.5 to 3.0). If your site breaks, you are on your own. The only way to fix your site in such a case is deleting all files and folders and restoring it from a backup. If you don't pay attention to this warning and the warning printed in Admin Tools' Joomla! Update page please do not complain if your site breaks.

Clicking on either of those buttons will start downloading the respective installation package. Once the download is complete, you are presented with the pre-installation page:

The Extraction method option defines how Admin Tools is going to attempt to overwrite your backup archive's files. The Write directly to files will attempt to have PHP directly overwrite the files. This will not work on most shared hosts. We, therefore, recommend using the second option, Upload using FTP, which will use FTP to overwrite the files. In this case, you have to fill in the following information on the lower part of the page:

FTP Host name

The host name of your site's FTP server, without the protocol. For example, ftp.example.com is valid, ftp://ftp.example.com is invalid.

FTP Port

The TCP/IP port of your site's FTP server. The default and standard value is 21. Please only use a different setting if your host explicitly specifies a non-standard port.

FTP User name

The username used to connect to the FTP server.

FTP Password

The password used to connect to the FTP server.

Initial directory

The FTP directory to your web site's root. This is not the same as the filesystem directory and can't be determined automatically. The easiest way to determine it is to connect to your site using your favourite FTP client, such as FileZilla. Navigate inside your web site's root directory. You'll know you are there when you see the file configuration.php and directories such as administrator, component, language, includes, cache and xmlrpc in that directory. Copy (in FileZilla it appears on the right hand column, above the directory tree) and paste that path in Akeeba Backup's setting.

Once you are ready to upgrade your site, you have two options to do that:

  • Update Joomla! will start performing the update right away.

  • Backup, then update Joomla! is only available if you have Akeeba Backup Core or Akeeba Backup Professional, version 3.1 stable or later, installed on your site. By clicking on this button you will be transferred to Akeeba Backup's Backup Now page. You can select the backup profile and start the backup once there. As soon as the backup is finished, Akeeba Backup will automatically send you back to Admin Tools which start the restoration procedure. We wanted to make sure that backing up and then upgrading your site requires only two clicks and no second thought.

When the restoration begins, you are presented with the update progress:

You can see how much of the installation package has been processed (Bytes read), how much data has been written to disk (Bytes extracted) and, finally, how many files have been extracted so far (Files extracted).

When the update is over you are redirected to the Admin Tools Control Panel. Admin Tools' Joomla! update icon turns to a green check mark reading "Up to date". That's it! Your Joomla! core is now updated.

What happens if I get a message about a truncated or corrupt archive?

If you get this error while updating the Joomla! core, your server does not permit downloading the upgrade package correctly. In this case, use the link to the Joomla! upgrade package in the "Joomla! Core Update" page to download the archive. Then, upload it to your site's temporary directory (as defined in your site's Global Configuration). By doing so, Admin Tools will detect that you have manually downloaded the update package and will not attempt to re-download it when you click on the Upgrade button.

In case that accessing your site is not possible after an interruption in the update process, do not panic. Go to http://joomla.org/download.html and download the latest upgrade package. Extract it locally, then upload all extracted files to your site, overwriting the existing ones. This is the manual upgrade process and is bound to work.

What do I need to setup on my server to allow Admin Tools to download the update information and upgrade packages?

You need to have either the cURL PHP module installed and activated or URL fopen() wrappers. Ask your host whether they provide either of these options. Furthermore, your host must allow TCP/IP connections over ports 80 and 443 to joomlacode.org and akeebabackup.com. If unsure, ask your host about it. Most hosts have a firewall in place and they will have to place exceptions at your request for Admin Tools' update features to properly work.

[Important]Important

On Windows hosts we strongly recommend installing and activating the cURL module.

Finally, while Admin Tools will try creating a writable subdirectory within your site's Temp-directory, this isn't always possible. We highly recommend having a writable temporary directory. If your host is running suPHP all you need is to give your site's Temp-directory 0755 or, on some few hosts, 0775 permissions. If your host is not running suPHP, you can follow one of the following alternatives.

The first alternative (easier, not recommended) is to give your temporary directory 0777 permissions. However, as this might adversely effect your site's security, we highly recommend uploading a .htaccess file by FTP inside this directory with the following contents:

order deny, allow
deny from all
allow from none

Give 0644 permissions to that file once uploading it. This way the temporary directory is made world-writable but inaccessible from the web, so that potential hackers can not exploit its lax permissions to attack your site.

The second alternative is more secure, but more messy as well. Start by visiting your site's Global Configuration and making sure that the path to the Temp-directory points to your site's tmp folder. Do note that you need to know the absolute path to that directory. If unsure, you can easily determine it. Place a file named temppath.php on your site's root with the following line as its only contents:

<?php echo dirname(__FILE__).DIRECTORY_SEPARATOR.'tmp'; ?>

You can access it from the web, e.g. http://www.example.com/temppath.php, and it will print out the absolute path to your site's Temp-directory. Remember to remove that file afterwards!

After you have gotten past that step, use your FTP client to completely remove the tmp directory from your site. Then, install Joomla! eXtplorer and create a new tmp directory in your site's root. If this doesn't work, you may want to ask your host about how you can temporarily make your site's web root world-writable in order to create that directory. Your host may complain about security reasons. Please direct them to this paragraph. We only need to make the web root writable for a limited amount of time, only long enough to create the new Temp-directory, and then reset its permissions to more safe settings.

Provided that you have created that directory, it is now owned by your web server user it is writable. Finally, for security reasons, you might also want to create a new .htaccess file inside that directory using eXtplorer, with the following contents:

order deny, allow
deny from all
allow from none