== Joomla Setup and Configuration ==

==Installation==
* Create MySQL database, user and password to be used by the Joomla system:<code>
$ mysql -u root -h localhost -p
mysql> SHOW DATABASES;
mysql> CREATE DATABASE joomla;
mysql> GRANT ALL ON joomla_db.* TO joomla_usr@localhost IDENTIFIED BY 'joomla_pass';
mysql> FLUSH PRIVILEGES;
</code>
* Download the software from http://www.joomla.org to the installation directory on the web server, such as ''/var/www/html''.
* Unpack the software in ''/var/www/html'', and set file ownership to web server process (in this case, ''apache''):<code>
$ cd /var/www/html
$ tar xzf Joomla_1.0.11-Stable-Full_Package.tar.gz
$ chown -R apache:apache *
</code>
* Point the browser to your website, such as http://www.example.com or http://www.example.com/joomla (if using ''joomla'' as the installation directory).
* Perform pre-installation check, and take care of issues listed there.
* Step 1: Enter database information
** Hostname: localhost
** MySQL Username: joomla_user
** MySQL Password: joomla_password
** MySQL Database Name: joomla_db
** MySQL Table Prefix: jos_
* Enable write permissions to file ''configuration.php'':<code>$ chmod a+rw configuration.php</code>
* Step 2: Enter site name.
* Step 3: 
** URL: http://www.example.com
** Path: /var/www/html
** Your E-mail: admin@example.com
** Admin password: adminpassword
* Step 4: 
** Remove the installation directory (''/var/www/html/installation'') for security reasons.
** Write down admin username and password.  
** Copy configuration to file ''/var/www/html/configuration.php''.  Make sure this file is set to read-only.

== Configuration ==
* Login to Administration page: http://www.example.com/administrator
* Change site template: Site > Template Manager > Site Template.  Search the Internet for more Joomla templates.
* Create site users: Site > User Manager

== Installing a Component Manually ==
Sometimes, due to permission restrictions on the server, it is not possible to install a component through the usual method (inside Joomla). You have 2 alternatives:
# Give more rights to the web server process to read/write the Joomla files and folders.
# Install the component manually.  Basically, copy the files using FTP, then register the component to the database using SQL.

Usually giving yourself more rights is a problem since you might be hosting and not managing the server.  To work around this problem, you need a different approach

===== Method 1: Totally Manual =====
Perform the following steps:
1. Analyze the installer XML file:
* Open the component installer (it should be a zip file). 
* Locate and open the installer XML file.

Sample Installer XML file:

<code xml>
<mosinstall type="component">
 <name>HelloForm</name>
 <creationDate>06/08/2006</creationDate>
 <author>John Doe</author>
 <copyright>© 2006, John Doe.  All rights reserved.</copyright>
 <license>
  This component in released under the GNU/GPL License (http://www.gnu.org/copyleft/gpl.html).
 </license>
 <authorEmail>jdoe@example.com</authorEmail>
 <authorUrl>www.example.com</authorUrl>
 <version>1.0</version>
 <description>
   This provides a basic Joomla component.
 </description>

 <files>
  <filename>helloform.php</filename>
  <filename>helloform.html.php</filename>
  <filename>helloform_settings.php</filename>
  <filename>helloform_settings.php.default</filename>
  <filename>language/english.php</filename>
 </files>

 <install>
  <queries>
   <query>DROP TABLE IF EXISTS `#__helloform`;</query>
  </queries>
 </install>

 <installfile>
  <filename>install.helloform.php</filename>
 </installfile>

 <uninstallfile>
  <filename>uninstall.helloform.php</filename>
 </uninstallfile>

 <uninstall>
  <queries>
   <query>DROP TABLE IF EXISTS `#__helloform`;</query>
  </queries>
 </uninstall>

 <administration>
  <menu>HelloForm</menu>
  <submenu>
   <menu act="config">Configuration</menu>
   <menu act="manage">Manage Items</menu>
  </submenu>
  <files>
   <filename>admin.helloform.html.php</filename>
   <filename>admin.helloform.php</filename>
   <filename>helloform.class.php</filename>
   <filename>toolbar.helloform.html.php</filename>
   <filename>toolbar.helloform.php</filename>
   <filename>help/index.html</filename>
   <filename>tmpl/com_admin.html</filename>
   </files>
 </administration>
</mosinstall>
</code>


2. Perform installation steps manually using the installer XML file as a reference:
* Copy the component files to the correct place. For example, assuming the component name is ''mycomp'': 
** Files listed under ''<files>'' should by copied to ''/joomla/components/com_mycomp''. 
** Files listed under ''<administration><files>...</files></administration >'' should by copied to ''/joomla/administration/components/com_mycomp''.
** Execute the SQL statements (using phpMyAdmin or MySQL client) to create whatever tables and fields are required by the component.  Only execute the SQL statements under ''<install><queries>...</queries></install>''.

3. Register the component on the server.  Basically, go to the Joomla database, under the components table (usually ''jos_components''), create a new record similar to the others. The fields must contain the relevant data from the new component.  

Note that:
* For every menu entry under ''<administration><menu>Parent Menu Entry ...</menu></administration>'' there will be an entry in table ''jos_components'', and the Parent ID will be 0.  
* For every menu entry under ''<administration><submenu><menu>SubMenu Entry ...</menu></submenu></administration>'' there will be an entry in table ''jos_components'', and the Parent ID (field `parent`) will contain the Record ID (field `id`) of the parent record (parent menu).

For example, these would be the records to add based on the XML installer:

^ id  ^ name ^ link ^  menuid ^ parent ^ admin_menu_link ^ admin_menu_alt ^ option ^ ordering ^ admin_menu_img ^ iscore ^ params ^
| 35 | HelloForm | option=com_helloform | 0 | 0 |  | Manage/Configure HelloForm | com_helloform | 0 | images/icon.png | 0 |  |
| 36 | Manage |  | 0 | 35 | option=com_helloform&act=manage | Manage HelloForm | com_helloform | 1 | images/icon.png  | 0 |  |
| 37 | Configuration |  | 0 | 35 | option=com_helloform&act=config | Configure HelloForm | com_helloform | 2 | images/icon.png | 0 |  |


Sample SQL statement:
<code sql>
INSERT INTO `jos_components` ( 
  `id` , `name` , `link` , `menuid` , `parent` , 
  `admin_menu_link` , `admin_menu_alt` , `option` , 
  `ordering` , `admin_menu_img` , `iscore` , `params` 
)
VALUES (
  NULL , 'HelloForm', '', 
  '0', '0', 'option=com_helloform', 'Manage/Configure HelloForm', 
  'com_helloform', '0', 
  'images/icon.png', 
  '0', ''
);
</code>

These are the descriptions of each field: 

^ Field ^ Description ^
| `id` | Record ID, which gets created automatically if NULL is used. | 
| `name` | Component name, such as ''MyComp''. |
| `link` | Link to the component, used for accessing the component frontend, such as ''option-com_mycomp''. |
| `menuid` | Menu ID, usually 0. |
| `parent` | Parent component ID.  If it is the main menu entry, this value is 0.  If it is a submenu entry, this value has to be the parent (main entry) ID. |
| `admin_menu_link` | Menu link to the component, which is only available under the administration menu. |
| `admin_menu_alt` | Menu name (or description) to used instead of plain menu link. |
| `option` | Any options specific to the component. |
| `ordering` | Ordering used in the menu listing. This is important for the submenu entries. |
| `admin_menu_img` | Icon to use beside menu entry. |
| `iscore` | Specified whether it is a core component (0=False, 1=True). |
| `params` | Any parameters specific to the component. |


===== Method 2: Practical Approach =====
An alternative way (probably the best way to approach the problem):
* Export your Joomla database using phpMyAdmin.
* Install that database locally on your PC.
* Install the component there.
* Backup your local database using phpMyAdmin.
* Recreate the database on the server using phpMyAdmin and your new backup.
* Copy your local files to the server (so that the component files are copied to the right place).

===== Method 3: Fast Approach =====
If you do not want to go through all this trouble, at least: 
* Create a local database using a backup copy from the server (use phpMyAdmin for export and import).  
* Install the component locally (use Joomla install process).
* Inspect what record it created locally under table ''jos_components''.  
* Register the component on the server.  Basically, write an SQL statement to create that record in table ''jos_components'' (use phpMyAdmin to execute the SQL statement). For example: <code sql>
INSERT INTO `jos_components` ( 
  `id` , `name` , `link` , `menuid` , `parent` , 
  `admin_menu_link` , `admin_menu_alt` , `option` , 
  `ordering` , `admin_menu_img` , `iscore` , `params` 
)
VALUES (
  NULL , 'MyComp', 'option=com_mycomp', 
  '0', '0', 'option=com_mycomp', 'MyComp', 
  'com_mycomp', '0', 
  '../administrator/components/com_mycomp/images/mycomp_x_icon.png', 
  '0', ''
);
</code>