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.
- 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.
[PHP] ; Configure for Joomla per security checklist ; http://docs.joomla.org/Security_Checklist_2_-_Hosting_and_Server_Setup 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.
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.
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
- If you are informed that one or more PHP settings are not at their recommended values, configure PHP as needed. For more information, see the Joomla project’s advice on common issues and error handling.
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 “firstname.lastname@example.org”.
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:
CONFIGURATION: WHAT YOU MUST DO
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.
CONFIGURATION: WHAT YOU MAY WANT TO DO
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.
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.
INSTALLATION TIPS AND TRICKS
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.
ADMINISTRATION TIPS AND TRICKS
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.
Something not working as expected? Try OS Training’s Essential Health Checks for Your Joomla Site.
scp is better than FTP or your web host’s administration controls for copying large files