Installing and configuring Joomla

Joomla is a popular and simple content management system (CMS) to run on a LAMP installation.

The following instructions are based on my experiences installing Joomla 1.0 through 2.5 locally on Linux and Windows, and remotely on FreeBSD- and Linux-based web hosts. Every operating system, distribution, and web host is different; YMMV and all that.

TODO: Break up this too-long article into three smaller ones: Preparation, Installation, Configuration & Next Steps.

If you are moving an existing site to a new server or Joomla installation rather than starting from scratch, use Akeeba Backup.

If installing remotely on a web host
Select an appropriate web host. Rochen Host is often recommended, and I am happy with Site5. At a minimum insist on a web host that provides:

  • a Unix-like operating system
  • recent stable versions of Apache, MySQL, and PHP
  • SSH access
  • a CGI wrapper such as php-cgiwrap or suexec to avoid ownership and permissions problems
  • Your own .htaccess and php.ini

For further information, see the Joomla documentation team’s suggestions for choosing a web host. Pay particular attention to the advice to avoid the cut-rate hosts that compete primarily on price (been there, done that). I’ve found Joomla Hosting Reviews to be particularly useful.

Insure your web host offers php-cgiwrap or a similar method to avoid ownership and permissions problems. Enable it before proceeding or be prepared for permissions hell; see this reference.

Every web host that offers php-cgiwrap has its own instructions; consult your host’s knowledge base or technical support staff. Perhaps how my host, Pair Networks, handles this will be illustrative:

First we use SSH to copy Pair’s php5.cgi to the cgi-bin subdirectory of your account’s Apache docroot:

$ cp /usr/www/cgi-bin/php5.cgi ~/public_html/cgi-bin/
$ chmod 755 ~/public_html/cgi-bin/php5.cgi

Then we enable php-cgiwrap in .htaccess in the Joomla docroot. Create or edit the file, adding this code:

# Enable Pair Networks php-cgiwrap - modify per your username
Action application/x-pair-sphp5 /cgi-sys/php-cgiwrap/USERNAME/php5.cgi
AddType application/x-pair-sphp5 .php

# Because php-cigwrap is being used, php variables for Joomla core
# cannot be set here; set them in php.ini

Be sure to change your username. php-cgiwrap is now enabled. This works even if the Joomla docroot is a subdirectory of the Apache docroot.

Local or remote installation
Insure that recent stable versions of Apache, MySQL, and PHP are installed. If this is a remote installation, your web host should have done the heavy lifting for you. If this is a local installation, see my Apache, MySQL, and PHP installation instructions.

Take note of default file ownership in the Apache docroot on the target system. On a local installation, it might be apache:username or www-, while on a remote installation it might be username:users. Keep the target system’s file ownership scheme in mind as you continue.

Gather the following MySQL information and have it ready for the Joomla installer:

  • host name
  • desired database name
  • user name and password

Host name is often localhost. To check, use phpMyAdmin or your web host’s database administration tool. In phpMyAdmin, the host name (a.k.a. database server name) is shown at the top of the main column. Alternatively, ask your hosting company or just try “localhost”.

The Joomla installer can create a database for you, but you will be asked what name you want to give it. I usually choose something on the order of “joomla2_5”.

You will need a user name with full privileges to create and drop tables. This can be done in phpMyAdmin or your web host’s database administration tool. Some web host’s tools cannot assign a user name without creating an associated database with it; in this case take note of the new database’s name and we will instruct Joomla to use it.

Configure PHP to use appropriate, secure variables for Joomla. The Joomla project recommends configuring PHP with php.ini. An example php.ini file with appropriate values is:

; Configure for Joomla per security checklist

disable_functions = show_source, system, shell_exec, passthru, exec, popen, proc_open
allow_url_fopen = Off
display_errors = Off
output_buffering = Off

; Set basedir to (1) Apache docroot and (2) backup directory outside docroot

open_basedir = /usr/www/users/USER:/usr/home/USER/backup

; Define temporary directory for uploads

upload_tmp_dir = /usr/www/users/USER/tmp

; Per-extension configuration per each extension's documentation, for example:

upload_max_filesize = 4M
max_execution_time = 60

Change the paths as appropriate. Save the file in the cgi-bin directory in the Apache docroot. This works even if the Joomla docroot is a subdirectory of the Apache docroot.

Download an appropriate version of Joomla. These instructions assume you have downloaded the .tar.gz version; otherwise consult the file unpacking instructions.

TODO: Link here to an explanation of the Joomla release cycle to help readers select the most appropriate version.

1. Copy the Joomla installer package to your Apache docroot or a subdirectory. On a local installation I created the directory /var/www/html/joomla1.6 (apache as owner, me as group, permissions 775) and copied the installer package there. If this is a remote installation, you will usually upload to the Apache document root, perhaps ~/public_html/. Throughout the rest of this document, this location will be referred to as the Joomla docroot.

Unpack the installer:

$ cd /path/to/joomla/docroot
$ tar -zxf Joomla_x.x.x-Stable-Full_Package.tar.gz

On a local installation, unpack it as the apache user to avoid permissions problems after installation. On a remote host, using php-cgiwrap lets you unpack as user.

2. In a web browser, open the page index.php in the Joomla docroot. On a typical local installation that might be http://localhost/joomla1.6/index.php. JavaScript and cookies must be enabled in the browser. Follow the instructions.

3. In the pre-installation check, correct all noted issues before proceeding. Well meaning people in support forums sometimes claim that these issues may be safely ignored; that advice is incorrect.

  • If you are informed that configuration.php is not writable, this is often a symptom of an underlying permissions problem which really should be addressed before continuing. If despite my advice you want to simply fix the immediate issue, you can create an empty configuration.php with permissions of 666:
cd /path/to/Joomla/docroot
touch configuration.php
chmod 666 configuration.php

4. In the database configuration, enter your database type (usually MySQLi), host name, user name, password, and desired database name. On some local installations I find it necessary to specify “localhost” for database host name even though the box has a defined hostname.

5. FTP Configuration should never be needed or used. Needing it indicates an unresolved permissions problem that should be resolved before, not after, installation. Further, using it opens a security vulnerability. If you must use it, enable it by setting “Enable FTP file system layer” to Yes. Enter your FTP username and password. You can leave “FTP Root Path” blank and click on the “Autofind FTP Path” button to fill it in. Then click on the “Verify FTP Settings” button. Open Advanced Settings and in “Save FTP Password” select Yes.

6. In Main Configuration, change the default admin username to something non-default. Make note of the username and password you have chosen. For admin email, you cannot use a local mailbox even if this is a local installation. You must provide an email address of the form “”.

7. When finished, delete or rename the directory installation/. As a security measure, the administrative backend will not launch until you do this. If you rename it, set its permissions to 700 and delete it as soon as practical.

The basic installation is done. Your backend (admin) URI is of the form:


Your username and password are those you chose during setup.

The site URL is of the form:


Insure that directory permissions are correct (Site – System Information – Directory Permissions). Do not proceed without insuring that all is well. It is commonly stated on support forums that under some circumstances unwritable directories can be safely ignored. This is not true.

If permissions are incorrect:

  • On a remote system, confirm that php-cgiwrap is enabled. This should be enough to solve the problem for a remote installation.
  • Insure that file and directory ownership is correct for the system. If not, then as root “chown -R user:group /path/to/Joomla/docroot/”. This should solve the problem for a local installation.
  • As a last resort, ask the web host to chown as needed. Be aware that this merely corrects the current symptoms and does not address the underlying issue that caused the permissions problems in the first place. Be attentive to the permissions of files created or modified after the host performs the chown.

Follow the instructions given in securing a Joomla installation.

In Site – Global Configuration – Site, take the site offline until it is ready. Modify the offline message and site name as desired. Set the default list limit to a size that fits your screen without scrolling; 15 works for me. Set the default feed limit as desired; I prefer a small value such as 5. Set “Feed Email” as appropriate. Enter site meta description and meta keywords as appropriate. Enable at least the SEF setting Search Engine Friendly URLs. Test immediately before and after enabling these settings. If these settings break the site (or if you merely want to understand Joomla SEF better), see this guide (written for Joomla 1.5 but still relevant). As you install and troubleshoot Joomla extensions later, keep in mind that some extensions do not work well with SEF settings enabled.

In Content Rights, place an appropriate copyright message.

In Site – Global Configuration – System, insure that the help server is set to the language of most backend users. If this is a local installation, you may want to increase the session lifetime. For development purposes, turn the cache off. For production use, turn it on.

In Site – Global Configuration – Server, enable gzip page compression. Set the time zone to match the physical location of the server. Insure FTP is disabled. Insure the mailer is set to PHP Mail unless you have reason to change it. Set database type to MySQLi to improve performance.

Create or modify a template for the site. Enable it and set any options at Extensions – Template Manager.

Assuming the site is not yet ready for public visitors, edit robots.txt to exclude all search engines. Remember to undo this when the site goes live.

Add any third-party extensions desired; see my notes on selecting extensions and on some specific extensions I have tried.

If desired, install language packs to accommodate the language needs of site visitors, users, or administrators.

Now customize Joomla as desired. A good place to start is Content – Article Manager – Options, where you can set default display options for sections, categories, and articles.

Perform another manual security check and backup.

Develop the good habit of always performing a manual security check and backup immediately before installing any extension or making any other significant change to Joomla. Then immediately afterward, do another manual security check to make sure no holes have been opened.

If this was a local installation, make a note of what you did about file ownership and permissions. You will have to do the same thing should you have to manually install something later.

If you take too long during the installation, the connection will time out and the installer will fail with a misleading error message beginning “An error has occurred: Cookies do not appear to be enabled…” To work around this, restart the process beginning with installation step 2, proceeding more quickly this time.

Customizing code
When I need to customize code to suit the client, I have found these best practices to be helpful:

1. Copy the file to be modified from the server to the local development workstation. Preserve the directory structure. For example, the file:


on the server was copied locally to


Insure that the local directory is included in your regular local backup routine.

2. Make a local copy of the file, labeled as original, and make it read only:

$cd ~/Documents/www/foobar/dev
$ cp .htaccess .htaccess-original
$ chmod u-w .htaccess-original

3. Modify the file (not the read only copy labeled original) as desired. Copy both the modified file and the file labeled original to the server.

Health Checks
Something not working as expected? Try OS Training’s Essential Health Checks for Your Joomla Site.

General information
scp is better than FTP or your web host’s administration controls for copying large files

Webhost-specific information
Pair Networks: Installing Joomla
Pair Networks: php-cgiwrap, suexec, and a comparison of the two


About Warren Post

So far: Customer support guy, jungle guide, IT consultant, beach bum, entrepreneur, teacher, diplomat, over-enthusiastic cyclist. Tomorrow: who knows?
This entry was posted in Uncategorized and tagged , , , . Bookmark the permalink.

9 Responses to Installing and configuring Joomla

  1. anonymous says:

    Anonymous writes:I use pair for my hosting and this helped me out! thanks for the easy to follow guide!

  2. wpost says:

    Glad to help. Pair Networks has worked out great for my Joomla installations, too.

  3. anonymous says:

    Muddauber writes:Thanks, Warren I use Rochen and PAIR and have been with PAIR for about 10 years.I continue to have problems with permissions and ownership and recently installed Joomla 1.5.23, cgi-wrap and thought I was good to go. When I went and ran my site (opening with a static splash page and using links with SEF, all the SEF links were 404'd!!!! When I turn off SEF, I'm back to my long extended URLs.Any suggestions on fixing this problem?

  4. wpost says:

    Hm, no idea. I moved a Joomla site to Pair from a cheap host precisely because of permission and ownership problems that the previous host was unable or unwilling to help with. With unrelated problems, I've found Pair's technical support to be stellar and well worth their premium price. I'd suggest asking them for assistance.It may be related or it may not be, but I've never had good experiences with SEF in Joomla, regardless of the host.Good luck, and if you find a solution, please shout back here.

  5. Pingback: Migrating a Joomla site to a new server with Akeeba Backup | A maze of twisty little passages

  6. Pingback: Backing up a Joomla site with Akeeba Backup | A maze of twisty little passages

  7. Pingback: Installing CiviCRM on Joomla | A maze of twisty little passages

  8. Pingback: Securing a Joomla installation | A maze of twisty little passages

  9. Pingback: Securing Joomla with GuardXT | A maze of twisty little passages

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s