Wednesday, January 6, 2010

Joomla! Installation Gotchas

After installing a number of Unix/Linux applications (at least the ones for which there is no convenient RPM in a repository somewhere) you get accustomed to the routine of "tar-xzf some_software-1.2.3.tar.gz", then "cd some_software-1.2.3", followed by "./configure", then "make", sometimes "make test", and finally "make install". It's just a little inconvenient when something isn't packaged that way and you actually have to find and read the install-readme file. Likewise, most LAMP (Linux Apache MySQL PHP) applications follow an install sequence of "cd my_webserver_root", "tar -xzf /my_downloads/some_lamp_app.tar.gz", "cd some_lamp_app", maybe "cp config.php-dist config.php", then "chgrp apache config.php" (or similar), and "chmod 775 config.php", followed by pointing the browser to "http://mywebsite/some_lamp_app/installer" (or similar). It's just a little inconvenient when something doesn't quite follow that pattern, and more so if it chews up time trying to figure out why something is subtly different. Joomla! has a few of those little time munchers so until they fix it, here are a few things that I stumbled over and how I got them fixed.

Unpacking Joomla!
It is just irritating to unpack any distribution and find that it has created more than a single directory within which the rest of the contents are unpacked. Unfortunately, Joomla! is distributed in an archive with no internal top level directory to contain the rest. Unless you want a few dozen files unpacked directly into your working directory, Create a directory first, change into that directory, and THEN
'tar -xzf Joomla_1.5.15-Stable-Full_Package.tar.gz'

FTP Layer Setup
Issue 1: If you get an message like: Error: the XML response that was returned from the server is invalid, you may have made the same mistake I made by copying /var/www/http/joomla_1_5_15/configuration.php-dist to configuration.php. Apparently, the installer script depends on code somewhere in the product that uses the ftp settings in the existing configuration.php file instead of what you filled in on the form. So, instead of copying configuration.php-dist, just create an empty configuration.php, adjust its permissions so that the installer can write to it at the end, and start the install process over. Also, since you would have already gone past the database table creation step, the advanced options on the database connection information page allow you to drop the previous tables before creating new ones.
Note: Even if you got through the install process, this same issue can show up the first time the actual Joomla site is accessed but the message may be something like: JError Unable to load Database Driver Starting with an empty configuration.php seems to avoid this too.

Issue 2:
If the "Verify FTP Settings" button reports that the ftp server may be incompatible, or it says that it the STOR ftp command failed, the Joomla! install directory is probably not writable and executable by the ftp user account (Note: Directories in a Unix/Linux file system must be 'executable' in order for their contents to be listed). Most likely this comes up because the ftp user account provided for Joomla's to use is a non-shell access account that is different from the owner of the files in the install directory. For example, if the ftp user account were 'joomlaftp' and the owner of the joomla files is set to a shell account called 'webmaster'). The group on the Joomla directory and files within it may be set to the group under which the webserver runs so that if the webserver process needs to write anything (e.g. an uploads directory) the write access can be granted using something like chmod g+w uploads. It probably wouldn't be a good idea to add the 'webmaster' group to the ftp user account's group list, because that could extend it's reach past the Joomla files, and defeat the purpose of even having the FTP Layer. It may not be practical to change the group on the Joomla files either. So, on most recent Unix/Linux distributions, ACL rules can provide more specific access on specific files, to a specific user or group. Add read/write/execute to the Joomla install directory for the special Joomla FTP account (-R is 'recursive' and -m is 'modify'):

setfacl -R -m u:joomlaftp:rwx /var/www/http/joomla_1_5_15

Then verify that the permissions now consist of the normal file system permissions plus the ACL.

getfacl /var/www/http/joomla_1_5_15
getfacl: Removing leading '/' from absolute path names
# file: var/www/http/joomla_1_5_15

# owner: webmaster
# group: apache

64 bit Linux Zip Library Bug
This has been reported to the Joomla! developers (see tracker 15044) but either they think it is a closed issue because they tested on a 32 bit system, or maybe it just isn't very high on the priority list because 64 bit Linux systems are a secondary concern. This issue may not affect more "bleeding edge" distributions but does affect CentOS 5 (i.e. RedHat Enterprise Linux 5) x86_64 distributions. If uploading a plugin or a template that is in pkzip (*.zip) format just silently fails on your 64bit system, you can try (at your own risk of course) applying this patch to the Joomla zip.php library code by saving the following patch file text into a file and running these commands...

cd /var/www/http/joomla_1_5_15/libraries/joomla/filesystem/archive
mv zip.php zip.php.orig
patch --ignore-whitespace < zip_php_fix.patch

------------- snip file: zip_php_fix.patch ----------------
--- zip.php.orig
+++ zip.php
@@ -223,8 +223,8 @@
function _extractNative($archive, $destination, $options)
- if ($zip = zip_open($archive)) {
- if (is_resource($zip)) {
+ $zip = zip_open($archive);
+ if (is_resource($zip)) {
// Make sure the destination folder exists
if (!JFolder::create($destination)) {
$this->set('error.message', 'Unable to create destination');
@@ -248,9 +248,8 @@
- }
} else {
- $this->set('error.message', 'Unable to open archive');
+ $this->set('error.message', 'Unable to open archive. Error code '.$zip);
return false;
return true;
------------- snip file: zip_php_fix.patch ----------------

It is a struggle to resist the urge to just shut off Security Enhanced Linux. SELinux is always locking up something to send you on a quest to figure out how to unlock it. Even if SELinux does some useful things in terms of protecting against intrusions or unauthorized modifications, it may just be a notch more difficult than sendmail to configure it correctly. That said, these rules for Joomla's files may not be exactly right, but they seem to give Joomla the access it needs while keeping SELinux set to enforcing. (Note: This assumes that everything in /var/www is already labeled by a default SELinux rule as httpd_sys_content_t but you may need to add a corresponding rule explictly if Joomla's install directory is elsewhere in the file system).

semanage fcontext -a -t httpd_sys_script_rw_t '/var/www/html/joomla_1_5_15/components(/.*)?'
semanage fcontext -a -t httpd_sys_script_rw_t '/var/www/html/joomla_1_5_15/configuration\.php'
semanage fcontext -a -t httpd_sys_script_rw_t '/var/www/html/joomla_1_5_15/images(/.*)?'
semanage fcontext -a -t httpd_sys_script_rw_t '/var/www/html/joomla_1_5_15/media(/.*)?'
semanage fcontext -a -t httpd_sys_script_rw_t '/var/www/html/joomla_1_5_15/modules(/.*)?'
semanage fcontext -a -t httpd_sys_script_rw_t '/var/www/html/joomla_1_5_15/plugins(/.*)?'
semanage fcontext -a -t httpd_sys_script_rw_t '/var/www/html/joomla_1_5_15/templates(/.*)?'
semanage fcontext -a -t httpd_sys_script_rw_t '/var/www/html/joomla_1_5_15/tmp(/.*)?'
restorecon -R -F -v /www/joomlainstalldir

No comments: