Brad Baker, a founding member of the Joomla project, likens not keeping your Joomla installation up to date to driving a racing car without a helmet or seatbelt. Here’s how to buckle up.
This article is for updating Joomla versions prior to 1.6. For Joomla 1.6 and later, see Upgrading from an existing version on the Joomla documentation project.
I often customize Joomla’s code, so I need a means of updating that gives me full manual control so that my work is not overwritten, as documented below. If you use Joomla out of the box, however, you might find that a tool such as Update Manager suits your needs and makes the task easier.
Are you updating or migrating? In Joomla-speak, updating means to go from one maintenance release to another — for example, from 1.5.22 to 1.5.23. Migrating means to go from one minor release to another — for example, from 1.5.23 to 1.6.0. This article focuses on updating.
Migrating adds additional issues which this article does not consider, but you should. For example, in the two migrations I have done — from 1.0 to 1.5, and 1.5 to 1.6 — all old extensions and templates had to be replaced with new ones. If you are migrating, you will want to confirm beforehand that adequate extensions and templates exist for your new version of Joomla. Also be sure to read the Joomla documentation project’s relevant migration guide.
Patches are released to upgrade from a particular version to a particular version. If for instance you are running Joomla 1.0.12 and want to upgrade to 1.0.13, you will need the 1.0.12 to 1.0.13 patch package. If you have a particularly old installation, you may have to apply multiple patches to get up to date. Recent patches are available from the download section of joomla.org; older patches are unofficially collected in Phil Taylor’s repository.
If you have done any customization to Joomla’s code, see if the patch will overwrite your customized files. To do this, first uncompress the patch package to a temporary directory on your local workstation. How you do this depends upon the compression format of the patch; in my order of preference they are:
- For a gzipped tar patch, tar -zxf patch.tar.gz
- For a bzipped tar patch, tar -jxf patch.tar.bz2
- For a zipped patch, unzip -o patch.zip
Then open a diff editor like Meld and do a directory comparison (File – New – Directory Comparison): one pane showing the patch directory and the other pane showing the directory of your customized files. Then simply browse the differences, making note of any customized files that will be overwritten. Incorporate any changes in the patched files to your customized files, because after we apply the patch on the server we will upload the customized files to overwrite the patch files. The end result will be files that are both patched and customized.
APPLY THE PATCH
You have three options. In order of preference, they are:
$ cd /path/to/patch/ $ scp patch.tar.gz firstname.lastname@example.org:public_html/ $ ssh email@example.com % cd public_html/ % tar -zxf patch.tar.gz % rm patch.tar.gz % exit
On a local installation, the procedure is similar. Determine the owner and group of Joomla’s files (on my local installation that is apache:apache). Then change the owner and group of the patch package accordingly, and uncompress it as that user. On my local installation the commands were:
$ su # cd /var/www/html/joomla1.5/ # cp /path/to/patch.tar.gz . # chown apache: patch.tar.gz # su apache $ tar -zxf patch.tar.gz $ rm patch.tar.gz
On my box, su apache gives the non-fatal error sh: /root/.bashrc: Permission denied which may be ignored.
2. The second best method is to upload and then uncompress the package using your web host’s file manager. Delete the patch package afterward.
3. As a last resort, uncompress the package locally and upload the files via FTP. The Joomla team pointedly discourages this.
Whichever method you choose, upload any customized files after applying the patch and to take the site back online.
Insure there are no obvious problems that need to be addressed. In particular take a look at Help – System Info – Directory Permissions. Also make sure third-party components are not obviously broken. As a final step, perform another security check run and manual backup.