NOTE: For an companion illustrated Installation Aid look here: viewtopic.php?f=429&t=376407. That would be a place to start before using the notes here. If your installation fails, come back and look at the steps in more detail here.
Your Joomla 1.5 installation is designed to be very easy for you. It can often be completed in less that 15 minutes.
This article outlines common problems that can occur with running the 1.5 installer with Apache 2 and MySQL. It concentrates on the Linux remote server but applies to local installs also. It suggests some possible resources and techniques for dealing with them.
There are some resource links at the end of the article for related topics.
If you are installing on Linux or another *NIX class server your may need an understanding of file and directory permissions. There is a good article on this by Brad Baker at: http://www.joomlatutorials.com/faq/view ... on/60.html.
Windows does not use permissions.
If you are on a shared host some of the defaults listed may be different. If you have multiple webserver domains already, there may be additional considerations. See the Joomla Forum for the topic virtualhost.
If your server uses mod CGI instead of running PHP as an Apache process (most common) there may be additional considerations. One major difference is that .htaccess is not available. mod CGI is sometimes selected because of the security advantages. This article has some references:
http://blog.rochen.com/2008/09/joomla-s ... -now-know/
System Configuration/Setup Problems.
1. You need a functioning webserver. The common choice is Apache. Version 1.x or Version 2.x. If you have a choice, use 2.x. This should have been installed as part of your XAMPP installation, MAMP installation, Linux Server installation, or other installation.
Make sure you know the location of your webserver's top-level html directory or server root. Joomla needs to be loaded there, or in a sub-directory, to be accessible. This is a directory path name, like the default /var/www/localhost/htdocs in Linux.
For XAMPP users, you may want to watch: http://www.veoh.com/collection/screenca ... 0A7Mnpe7z# . Ignore the commercial.
Try the webserver with your browser and make sure you can see its default home page. For example, http://localhost or http://127.0.0.1 works on most local hosts. If your server is remote you should use the domain name you were assigned. For example, http://www.mydomain.com or http://188.8.131.52, use what your host provided. If this is OK go to point 2.
There may be a specific port number that is needed to reach the webserver. Webservers are setup to listen on specific ports for requests. The default for most servers is 80, this is what your browser will default to. If you have a local server, it may be in the range 8080 - 8889, to avoid conflicts with other servers. If you cannot reach the webserver with this test, make sure you have the correct webserver URL and port number.
The port number is appended to the domain in your URL with a colon. For example:
If you cannot find a note in your installation instructions on port numbers, look in the Apache configuration file httpd.conf for the the Listen statement. For Linux users the default is in /etc/apache2. The port number should be listed. You can either append it to your URL when using the browser or change it to 80. If you change it make sure it will not conflict with other servers you are running.
There is documentation on Apache directives at: http://httpd.apache.org/docs/2.2/mod/directives.html. You will see Listen in the list.
If you more documentation on port numbers, there is a regulatory agency that lists all the port number assignments: http://www.iana.org/assignments/port-numbers. Look in the left column for your software type you suspect and across for the port number. This may provide some guidance. You will see that 8080 is an alternate for port 80 and 8089 - 8096 are unassigned, for example.
2. You need a functioning PHP language installation of 4.3.10 or newer with the defaults Joomla suggests. These are usually the PHP installation defaults. These can be viewed in the php.ini file. For Linux users the default is in /etc/php/apache2-php5.
Make sure your PHP is running. Use your browser to check this with the phpinfo() function. Most sites have a default script for this purpose. For example, http://localhost/phpinfo.php or php-info.php or a similar command for your configuration. If phpinfo does not produce a browser page with the PHP configuration details, you should troubleshoot this first.
It may be that your installation uses a different name for the phpinfo script, or one is not present. You can make your own with a text editor. Open notepad, or vi (or vim) on Linux and create this simple one line PHP script named phpinfo.php:
Code: Select all
<?php phpinfo(); ?>
Then copy it to the document root of your webserver. Retest the URL with the browser again.
There is documentation at: http://us2.php.net/manual/en/index.php.
3. You need an empty, writable database for Joomla to create its tables and store your content. Make sure your user name has adequate permissions to create and write to new tables. The most common database is MySQL. It should have been installed for you with one of the methods mentioned above. To create a database for Joomla use an administration tool such as phpMyAdmin, also should have been installed with the database. Make sure to select the UTF-8 collating sequence to get the correct storage and retrieval from your database.
You will need the exact user name and password used to create the database during the installation. Make a note of them and the database name. If you do not have this information you cannot install Joomla. It does NOT create the database for you. There should be online documentation for the phpMyAdmin program at: http://www.phpmyadmin.net/home_page/docs.php.
There are other tools to use to create the database. In Linux your system may have webmin installed, for example. You can access it at port 10000, http://www.mysite.com:10000.
4. Download the latest Joomla stable release from http://www.joomla.org. Copy it to your webserver document root or a sub-directory of that path. Then unzip it. If there are any unzip errors, don't ignore them. Replace the download and try again.
5. You also need a blank, writable, file called configuration.php. If it is not totally empty is must not have more than 10 characters in it. The configuration.php-dist file is not a candidate. Just create a new file and copy it to the webserver document root or where you unzipped Joomla.
6. Check that your Apache webserver DirectoryIndex directive list contains index.php. It is best to make it the first entry. This is in your httpd.conf file at the location mentioned above. If this is missing you will not get the Joomla installer to start. Instead you will just get a list of the files in the directory, your default home page, or perhaps nothing. Point 1 above has a link to the Apache directives that include this.
You should be ready for your Joomla installation now.
To start the installation just browser to the location where you unzipped Joomla. If your DirectoryIndex is setup as above, and you use the correct URL (similar of the same as the Webserver test step above) the Joomla installation Language selection page should come up. If it does not, review the steps above, and make sure the browser address you are using is correct.
For example, http://localhost, or http://www.mysite.com, or http://www.mysite.com/joomla depending on your configuration.
Joomla Installer Problems.
The installer has a seven step sequence it leads you through. Let's look at each step for its potential challenges.
One finer point is that the installer uses 15 minute session timeouts. If you pause on an installer page for more than 15 minutes, you will get a cookie error. To recover click previous. You will have to start at step 1 again. There is nothing wrong with your browser setup, unless you have cookies disabled. This should have raised an error at the outset, anyway.
You can open another window while in the installer, and try to resolve problems and perform forgotten preparation. For example, creating the database or the configuration.php, write enabling configuration.php, or removing the installation directory at the end before launching the admin pages.
Step 1: Language Selection. There are over 30 language choices. If one of these is not your written language, you have a couple of choices. Have a friend help you with the installation who understands one of the languages listed. Use the Google translation tools to work with each page as you proceed. It may be able to translate to your written language.
There are only 7 or 8 pages to contend with. The translation page link is
Step 2: Pre Installation Check. If there are any RED NO values these are best dealt with before proceeding. There are a couple of basic ways to to do this. You can edit your php.ini file at the location mentioned above, or add a statement to your .htaccess file. The former may be easier. The latter requires you edit htaccess.txt and rename it to .htaccess (note leading dot). Copy htaccess.txt to your local system for editing and back to the server, if necessary.
Code: Select all
For example ,
php_flag register_globals off
Turns off the Register Globals if they are on, using the .htaccess file
The php.ini directives are documented at: http://us3.php.net/manual/en/ini.core.php.
The .htaccess statements are documented at: http://us3.php.net/manual/en/configuration.changes.php.
If you cannot make a blank, writable configuration.php, you can still complete the installation. There is a text box that will contain the configuration information for this file at the end of the installation. You need to paste this information to a file called configuration.php BEFORE leaving the installer.
Step 3: License. Should not be a issue unless you take more than 15 minutes to read it. If so, you will get a cookie error, as discussed above.
Step 4: Database Configuration. The database user name, password, and database name must be EXACTLY as in the previous section point 3. above, where the database was created. The installer will automatically preserve your existing tables, if this is a reinstall, as a bak_ set unless told to erase them. Note: backup has only one level. If you run the installer several times, and do not do your own backup, your backup tables may be empty.
Step 5: FTP Configuration. You can skip this step and still install Joomla. For Linux installations this is not recommended, unless you do not have the details requested. One of the first things you may want to do with your system is add some extensions that are not part of the installer procedure. The FTP layer is used for this. This step enables the use of this layer. The auto find and verify tools available are great to simplify setting up the FTP layer.
The FTP user name and password requested are not necessarily the same as your database. For Linux users, these should be the same as those used with your FTP client, when Joomla was uploaded to your server. When the values are entered, use the verify button check them. If they are correct the yes radio position will be set. Make sure the root path is your webserver document root.
Step 6: Site Configuration. You define the administrator and load sample data here. Joomla is much easier to learn with sample data. You should load this by CLCKING the button for it.
Pick a secure password. A simple rule of thumb is to use alternating upper and lower case letters and at least two numbers. A minimum length of eight is best. There is a nice site that will generate user passwords and .htaccess passwords at: http://tips-scripts.com/free.
When you define the site and administrator details make sure you are providing the site name that reaches your server. Most hosted sites will reach you with or without the leading www. node names, but not all.
Note that NO administrator name is requested. The default used is "admin". This is what you use to get logged into the administrator pages at first. Change it for better security on your first session.
The email address will be used in all the administration email generated by Joomla. Pick one that you want to be public.
Step 7: Finished. If you did not provide a writable configuration.php, look for the text box with the details to be copied to this file now. Your site cannot come up without a configuration.php.
Before you can use your new Joomla site you need to remove the installation directory. Joomla uses this and the configuration.php as flags to indicate your sites status.
If configuration.php is present and has more than 10 characters it assumed your site is installed and proceeds to try to load it. If the installation directory is found, it requests you remove it first. For example, if you are reinstalling you need to empty the configuration.php file before starting over, or you will get the remove installation directory message instead.
There are two options at the top of this page to use to proceed. Selecting one of these is intended. The admin option let's you go to the Joomla back-end and tune your settings. Exiting without either choice is not preferred. If you do this remember that the administrator pages are reached with:
You may want to backup your configuration.php separate from the server root, as a precaution. If this file is lost, damaged, or hijacked you can restore it to the original. You may also want to double check it for errors and typos.
You will be tuning it for a while, from the global configuration in the administrator pages, so it will need to be writable. As soon as possible you should protect this file. It is one of the ways that hackers hijack your site. There are several ways to do this. The simplest is to set its permissions to 666, so that it is only readable. You can also use .htaccess to restrict it to you and/or your IP address, etc. Finally you can hide it in another directory and have Joomla reference it indirectly when it loads. See the security FAQ for details.
Hopefully you are up and enjoying your new Joomla site at this point.
If you were not successful on your first installation attempt, or you decide to start over to get a fresh copy after experimenting, there is a simple procedure for this. You need to empty your configuration.php file and add your installation directory back to the site.
If you want to preserve any content you created, it is best to backup your database first with your phpMyAdmin or other software. Joomla will build a copy of your tables with prefix bak_ automatically, but this is a good precaution as well. If you restart more than once the data may be lost, otherwise. If you do not want the database Joomla will empty the tables for you automatically.
To restore your database you can use your phpMyAdmin tool, or MySQL from the command line. See this for procedures: http://video.google.com/videoplay?docid ... 6318372444, or: http://docs.joomla.org/Copying_a_Joomla_website.
If you have added extensions, that you want to preserve, this is a bit complicated. Joomla will write over the existing copies of its directories. This will prevent use of most of the extensions that were added after the last install. Some modules will still be usable but probably none of the plugins and components that were added.
Unfortunately you will need to remove these extensions manually by deleting the directories and files associated with them. The extension installer will NOT reinstall doing an automatic uninstall first. Since it does not know about the extensions you had in the last install, it will fail with an "ALREADY EXISTS" message. The best practice may be to backup your existing Joomla directory, or move it out of the way, and add the extensions back after the installation.
If you have any tweaks they will be lost by overwites. Back them up first.
Upgrades have a separate set of files and procedures to use. The upgrade files can be downloaded from the same loacations as he full release. A backup of the complete site before this procedure is a good practice.
Some guidelines are provided here: http://docs.joomla.org/Upgrading_1.5_fr ... 5x_version.
Once the new files are in place there may be a number of finer points to deal with. Your templates and extensions should not be assumed to be OK with the changes. There are several steps that should be checked, or you may waste a lot of time chasing phantoms.
1. Use the template manager to double check all of your menu assignments. Links can get broken. Assume this is almost like a new template install.
2. Visit your extension providers site and check the documentation and forums for any compatibility issues. Do the same on the Joomla Forum.
3. Consider running a series of tests on a duplicate site before bringing the upgraded site online.
In short the upgrade procedure does not handle all issues by itself. It has no knowledge of the specifics of your site, just the Joomla released software.
Administering Your Joomla System
There are many great articles on how to administer your system. Some of the most useful at first may be include the following.
3. http://docs.joomla.org/How_do_you_choos ... ensions%3F
4. http://docs.joomla.org/How_do_you_recov ... assword%3F
8. http://community.joomla.org/magazine/ar ... -data.html
9. https://www.opensourcesupportdesk.com/o ... os?catid=6
10. http://joomlaforbeginners.com/joomla-1. ... /index.php
Use the Joomla Forum to share an learn. There are over 100,000 members. Some of them will share your level of experience and concerns.
Customizing/Tuning Your New Joomla Site.
Out of the box, Joomla has a tremedous amount of value. You can now concentrate on making the site have the look and feel you wish, without as much coding to perform, or contract for. There may still be some tweaking to do. Some useful articles on this, perhaps, include the following.
1. http://docs.joomla.org/How_do_you_add_a ... osition%3F
2. http://docs.joomla.org/How_do_you_put_a ... article%3F
7. http://docs.joomla.org/Tutorial:Creatin ... Joomla_1.5
8. http://docs.joomla.org/Tutorial:More_on ... 21_modules
10. http://docs.joomla.org/Setting_up_your_ ... evelopment
If this information has any value, if may be to save you time. I hope it helps you get a faster start.
Enjoy - dpminusa.