Recent changes to Installation Guide

Installation Guide modified by Ghislain Bidaut

Ghislain Bidaut — Wed, 11 Sep 2013 08:00:51 -0000

--- v6
+++ v7
@@ -348,6 +348,7 @@
 #### Step 3: Data spaces configuration

 This section applies to both storages, database and files. The form has to be filled with the following values:
+
 - Files directory  the path of the directory where the uploaded data files will be stored._(see above)_
 - Driver   MySQL or PostgreSQL
 - Host     localhost

Installation Guide modified by Ghislain Bidaut

Ghislain Bidaut — Wed, 11 Sep 2013 08:00:04 -0000

--- v5
+++ v6
@@ -369,7 +369,8 @@
 You can create a user access for Djeen, by clicking on the 'Create' button in Front-end access section.

 To finish the configuration process without creating the menu item, you MUST click on the Close icon on the top right of the interface.
-Modify user access for Djeen
+
+### Modify user access for Djeen

 If you want to change some parameters of the user access created above (like for example the menu in which it is displayed or its position in the menu):

Installation Guide modified by Ghislain Bidaut

Ghislain Bidaut — Wed, 11 Sep 2013 07:59:07 -0000

--- v4
+++ v5
@@ -75,7 +75,7 @@

 Add a php_info.php script to your document root:

-    echo '  ' > /var/www/php_info.php
+    $ echo '  ' > /var/www/php_info.php

 Connect to http://SERVER_NAME/php_info.php
 You should get nicely formatted tables about your web server installation.
@@ -84,12 +84,11 @@

 #### Perl

-    Under the shell, type the command below:
-
-    perl -e 'use CGI; my $q=new CGI(); print "CGI OK!"'
-
-
-    It should not return any error.
+Under the shell, type the command below:
+
+    $ perl -e 'use CGI; my $q=new CGI(); print "CGI OK!"'
+
+It should not return any error.

 ### Joomla! installation

Installation Guide modified by Ghislain Bidaut

Ghislain Bidaut — Wed, 11 Sep 2013 07:57:27 -0000

--- v3
+++ v4
@@ -59,7 +59,9 @@
 #### Apache
 The web server is accessed by use of its internet name (my_computer.my_company.fr) or its IP address (10.1.1.1). If you install a test instance, this might be localhost. Whatever name is chosen, it will be referred here as SERVER_NAME.

-By default Apache provides access to documents located in the folder stated as DocumentRoot in its configuration. This folder corresponds to the root of the web server as seen from a user point of view, ie. http://SERVER_NAME/, which is the ROOT_URL of the web server. This folder varies on Linux distributions. It is either /var/www (CentOS), either /var/www (Ubuntu). The Apache configuration file is httpd.conf (CentOS) or /etc/apache2/sites-available/default (Ubuntu). It could also be found with: find /etc -name httpd.conf; find /var -name httpd.conf
+By default Apache provides access to documents located in the folder stated as DocumentRoot in its configuration. This folder corresponds to the root of the web server as seen from a user point of view, ie. http://SERVER_NAME/, which is the ROOT_URL of the web server. This folder varies on Linux distributions. It is either /var/www (CentOS), either /var/www (Ubuntu). The Apache configuration file is httpd.conf (CentOS) or /etc/apache2/sites-available/default (Ubuntu). It could also be found with: 
+
+    $ find /etc -name httpd.conf; find /var -name httpd.conf

     Directory  ROOT_URL
     /var/www/  http://SERVER_NAME/
@@ -267,7 +269,8 @@
         Allow from all
     

-Restart
+Restart with:
+
     $ service httpd restart (CentOS) or service apache2 stop; sleep 10; service apache2 start (Ubuntu)

 ### Directories configuration

Installation Guide modified by Ghislain Bidaut

Ghislain Bidaut — Tue, 03 Sep 2013 07:46:57 -0000

Installation modified by Ghislain Bidaut

Ghislain Bidaut — Mon, 02 Sep 2013 15:08:43 -0000

--- v1
+++ v2
@@ -10,31 +10,28 @@
 ### Client
 All the features have been validated for the following browsers:

-    Firefox 7+
-    Chrome 16+
+- Firefox 7+
+- Chrome 16+

 ### Server

-    Unix OS
-
-    Apache server (on Linux: package httpd or apache2)
-
-    Perl version 5.x (required for the upload functionality, see below)
-
-    PHP version 5.3+
-    Several additional PHP libraries:
-        libmcrypt
-        php-mcrypt
-        php-mysql
-        php-pdo _(not available on Ubuntu, already integrated)
-        php-pgsql (if PostgreSQL is chosen as Djeen database, see below)
-
-    Database management system(s): the Joomla! database requires a MySQL database, while the Djeen database can be either a MySQL base or a PostgreSQL base; so install PostgreSQL if you choose it for Djeen data storage.
-        MySQL database system AND server (on Linux: packages mysql and myqsl-server)
-        PostgreSQL database system AND server (on Linux: packages postgresql and postgresql-server)
-        Optionally, phpmyadmin and pgmyadmin to get a Web user interface for those database engines.
-
-    Some disk space to store files
+- Unix OS
+- Apache server (on Linux: package httpd or apache2)
+- Perl version 5.x (required for the upload functionality, see below)
+- PHP version 5.3+
+- Several additional PHP libraries:
+ - libmcrypt
+ - php-mcrypt
+ - php-mysql
+ - php-pdo _(not available on Ubuntu, already integrated)
+ - php-pgsql (if PostgreSQL is chosen as Djeen database, see below)
+
+Database management system(s): the Joomla! database requires a MySQL database, while the Djeen database can be either a MySQL base or a PostgreSQL base; so install PostgreSQL if you choose it for Djeen data storage.
+- MySQL database system AND server (on Linux: packages mysql and myqsl-server)
+- PostgreSQL database system AND server (on Linux: packages postgresql and postgresql-server)
+- Optionally, phpmyadmin and pgmyadmin to get a Web user interface for those database engines.
+
+- Some disk space to store files

 Note: installation was originally tested on Linux CentOS 5.5 and 6.0 operating systems; it has been adapted for Ubuntu/Debian also.
 Perl and libraries
@@ -44,45 +41,46 @@
 Under Unix prompt, a locate CGI.pm will help to find out if the file exists somewhere on the server.
 If the file is not present, it has to be installed either with the package manager, either with the cpan tool (or perl -MCPAN -e shell).

-    CPAN way:
-    On the first use, CPAN will ask for configuration. It is possible to simply answer yes at the first question to have CPAN configure itself automatically. Then, under the CPAN prompt, the CGI package can be installed with install CGI.
-    If there is an error during the installation process, an upgrade command is necessary. The CGI library can then be installed normally with install CGI.
+- CPAN way:
+On the first use, CPAN will ask for configuration. It is possible to simply answer yes at the first question to have CPAN configure itself automatically. Then, under the CPAN prompt, the CGI package can be installed with install CGI.
+If there is an error during the installation process, an upgrade command is necessary. The CGI library can then be installed normally with install CGI.

 ### Installation of required packages under Ubuntu 10.4

 Packages should be named with their version. Required packages (except Perl) should be installed with a command like:

-sudo apt-get install mysql-client-5.1 mysql-server-5.1                # Mysql
-sudo apt-get install postgresql-8.4 postgresql-client-8.4             # Postgresql
-sudo apt-get install libmcrypt4 php5-mcrypt php5-mysql php5-pgsql     # PHP
-sudo apt-get install apache2-mpm-prefork libapache2-mod-php5          # Apache
-sudo apt-get install perl libcgi-pm-perl                              # Perl, CGI.pm
-
-Check your set up
-URL and PATH
-
+
+    $ sudo apt-get install mysql-client-5.1 mysql-server-5.1                # Mysql
+    $ sudo apt-get install postgresql-8.4 postgresql-client-8.4             # Postgresql
+    $ sudo apt-get install libmcrypt4 php5-mcrypt php5-mysql php5-pgsql     # PHP
+    $ sudo apt-get install apache2-mpm-prefork libapache2-mod-php5          # Apache
+    $ sudo apt-get install perl libcgi-pm-perl                              # Perl, CGI.pm
+
+#### Apache
 The web server is accessed by use of its internet name (my_computer.my_company.fr) or its IP address (10.1.1.1). If you install a test instance, this might be localhost. Whatever name is chosen, it will be referred here as SERVER_NAME.

 By default Apache provides access to documents located in the folder stated as DocumentRoot in its configuration. This folder corresponds to the root of the web server as seen from a user point of view, ie. http://SERVER_NAME/, which is the ROOT_URL of the web server. This folder varies on Linux distributions. It is either /var/www (CentOS), either /var/www (Ubuntu). The Apache configuration file is httpd.conf (CentOS) or /etc/apache2/sites-available/default (Ubuntu). It could also be found with: find /etc -name httpd.conf; find /var -name httpd.conf
-Directory  ROOT_URL
-/var/www/  http://SERVER_NAME/
-Web
-
-    Try connection to your web server: http://SERVER_NAME/
-    You should get the Apache 2 Test Page powered by CentOS (CentOS) or something like 'It works!' (Ubuntu).
-    Apache is working!
-
-PHP
-
-    Add a php_info.php script to your document root:
+
+    Directory  ROOT_URL
+    /var/www/  http://SERVER_NAME/
+
+Try connection to your web server: http://SERVER_NAME/
+You should get the Apache 2 Test Page powered by CentOS (CentOS) or something like 'It works!' (Ubuntu).
+
+Apache is working!
+
+#### PHP
+
+Add a php_info.php script to your document root:

     echo '  ' > /var/www/php_info.php

-    Connect to http://SERVER_NAME/php_info.php
-    You should get nicely formatted tables about your web server installation.
-    PHP is working! (you should remove this script)
-
-Perl
+Connect to http://SERVER_NAME/php_info.php
+You should get nicely formatted tables about your web server installation.
+
+PHP is working! (you should remove this script)
+
+#### Perl

     Under the shell, type the command below:

@@ -92,83 +90,87 @@
     It should not return any error.

 ### Joomla! installation
-URL and PATH

 For sake of simplicity, Joomla! will be installed in the DocumentRoot tree in the following. You can either install Joomla! directory in the root or inside a sub-directory. Here is a directory/URL matching table supposing that DocumentRoot refers to /var/www :
-Joomla directory   ROOT_URL    JOOMLA_URL  JOOMLA_URL_PATH
-/var/www/  http://SERVER_NAME/     http://SERVER_NAME/     /
-/var/www/djeen/    http://SERVER_NAME/djeen    http://SERVER_NAME/djeen    /djeen
-
- Create a specific directory for Djeen
-cd /var/www
-mkdir djeen
+
+    Joomla directory   ROOT_URL    JOOMLA_URL  JOOMLA_URL_PATH
+    /var/www/  http://SERVER_NAME/     http://SERVER_NAME/     /
+    /var/www/djeen/    http://SERVER_NAME/djeen    http://SERVER_NAME/djeen    /djeen
+
+Create a specific directory for Djeen
+    $ cd /var/www
+    $ mkdir djeen

 Download and unpack
 First, Joomla! must be installed.

-    Download archives and installation instructions are found at http://www.joomla.org/.
-    (Instruction manual, if needed)
-
- Code for English version, change the link for other language
-wget http://joomlacode.org/gf/download/frsrelease/16914/73508/Joomla_2.5.4-Stable-Full_Package.zip 
-cd djeen
-unzip ../Joo*zip
-
-    Important: For the moment, Djeen can only be installed on a Joomla! version 1.5 website, due to compatibility problems between Djeen and the most recent versions of Joomla! (1.6 and above).
-
-    Uncompress the downloaded Joomla! archive into a directory under the DocumentRoot. NB: the archive does not contain a root folder, so the files will be unzipped directly in the current folder.
-    Usually, it is recommended to set the owner of the unpacked tree to the user running the Apache daemon. This insures that the web interface will access the Joomla! tree. You will not have to modify permissions for any component later, because component will be installed with the Apache user.
-    You can find the real user running Apache with: ps -edf | grep apache
-    On Ubuntu, this user is www-data, and its group is www-data.
-
-     Change the owner of Joomla! directory to apache user
-    chown -R www-data.www-data .
+Download archives and installation instructions are found at http://www.joomla.org/.
+
+This is the code for English version, change the link for other language
+    $ wget http://joomlacode.org/gf/download/frsrelease/16914/73508/Joomla_2.5.4-Stable-Full_Package.zip 
+    $ cd djeen
+    $ unzip ../Joo*zip
+
+Important: As of now, Djeen can only be installed on a Joomla! version 1.5 website, due to compatibility problems between Djeen and the most recent versions of Joomla! (1.6 and above).
+
+Uncompress the downloaded Joomla! archive into a directory under the DocumentRoot. NB: the archive does not contain a root folder, so the files will be unzipped directly in the current folder.
+Usually, it is recommended to set the owner of the unpacked tree to the user running the Apache daemon. This insures that the web interface will access the Joomla! tree. You will not have to modify permissions for any component later, because component will be installed with the Apache user.
+You can find the real user running Apache with: 
+    $ ps -edf | grep apache
+On Ubuntu, this user is www-data, and its group is www-data.
+
+Change the owner of Joomla! directory to apache user
+    $ chown -R www-data.www-data .

 #### On-line guided installation

 Joomla! installation is very well documented and you will be guided at each step, so you shouldn't encounter any notable difficulty. To start, just type the JOOMLA_URL into your web browser to begin the installation.

-Below are a few more precisions of each step.
-Step 2. Pre-installation check
+Below are additional indications for each step.
+
+##### Step 2. Pre-installation check
 In the Recommanded settings sub-section, if the Display Errors parameter is reported as 'On', you should:

-    go into your PHP configuration file (PHP.ini)
-    search for the line display_errors = On
-    set the value to Off
-    restart Apache server to have the new value taken into account
-    go back under your web browser and the Joomla! installation and click on the "Check again" button on the top right of the screen.
+- go into your PHP configuration file (PHP.ini)
+- search for the line display_errors = On
+- set the value to Off
+- restart Apache server to have the new value taken into account
+- go back under your web browser and the Joomla! installation and click on the "Check again" button on the top right of the screen.

 Letting the 'On' value will not cause any problem during the rest of the installation process. But once it's finished, the Joomla! website will have a very unpleasant display, with a LOT of warning messages, rending the navigation uncomfortable.
-Step 4. Database configuration
+
+##### Step 4. Database configuration

 You should only pay attention to the Basic settings sub-section.

 A default configuration would be as follow:
-Database Type  MySQL
-Host Name  localhost
-User Name  root
-Password   password of the aforementioned user
-Database Name  joomla_db
-Step 5. FTP configuration
+    Database Type  MySQL
+    Host Name  localhost
+    User Name  root
+    Password   password of the aforementioned user
+    Database Name  joomla_db
+
+##### Step 5. FTP configuration

 Djeen doesn't need FTP, so you can skip this step and go directly to the next one.
-Step 6. Main configuration
+##### Step 6. Main configuration

 Example data are not needed, so just don't worry about the related sub-section if it's still checked.
-Step 7. Finish
+##### Step 7. Finish

 Once you have - as requested - deleted the 'installation' directory, click on the 'Admin' button on the top right corner of the screen to access the administration section of your Joomla! website. It's from there that you will install the Djeen component later.
-Djeen installation
-Outline
+
+## Djeen installation
+
 In this section, we will set up the storage environment for Djeen. Djeen stores data in two spaces:
-a) the database space, in which objects are described are linked to files, and
-b) the file storage itself, meaning that data files are external from the database. Here we will set up both spaces.
-
-    add a database user allowed to manage databases
-    update access to the database
-    add Perl CGI support to Apache
-    change permission (usually not needed)
-    set up storage
+- a) the database space, in which objects are described are linked to files, and
+- b) the file storage itself, meaning that data files are external from the database. Here we will set up both spaces.
+
+- add a database user allowed to manage databases
+- update access to the database
+- add Perl CGI support to Apache
+- change permission (usually not needed)
+- set up storage

 ### Database initialization

@@ -178,79 +180,78 @@
 - allowed to create databases
 - with a password

-    In the following, we chose arbitrarily to name this user test (but could be also djeen).
-
-Choice A) MySQL database
+In the following, we chose arbitrarily to name this user test (but could be also djeen).
+
+#### Choice A) MySQL database

 Under Unix prompt:

-mysql -u root
-
-create user test@localhost identified by 'TYPE_HERE_THE_PASSWORD_OF_TEST';
-
-revoke super on *.* from test@localhost;
-
-grant create on *.* to test@localhost;
-grant alter on *.* to test@localhost;
-grant select on *.* to test@localhost;
-grant insert on *.* to test@localhost;
-grant update on *.* to test@localhost;
-grant delete on *.* to test@localhost;
-grant drop on *.* to test@localhost;
-grant lock tables on *.* to test@localhost;
-
-    Note 1: for the create user instruction, the password has to be typed between quotes.
-    Note 2: don't forget to mention the host (@localhost) after the user name.
-    Note 3: privilege lock tables is required to perform database dumps.
+    $ mysql -u root
+
+    >create user test@localhost identified by 'TYPE_HERE_THE_PASSWORD_OF_TEST';
+    >revoke super on *.* from test@localhost;
+    >grant create on *.* to test@localhost;
+    >grant alter on *.* to test@localhost;
+    >grant select on *.* to test@localhost;
+    >grant insert on *.* to test@localhost;
+    >grant update on *.* to test@localhost;
+    >grant delete on *.* to test@localhost;
+    >grant drop on *.* to test@localhost;
+    >grant lock tables on *.* to test@localhost;
+
+- Note 1: for the create user instruction, the password has to be typed between quotes.
+- Note 2: don't forget to mention the host (@localhost) after the user name.
+- Note 3: privilege lock tables is required to perform database dumps.

 Alternative: Use PhpMyAdmin on the database server.
-Choice B) PostgreSQL database
+#### Choice B) PostgreSQL database

 Under the Unix prompt (you might do sudo su to become super user first):

-su - postgres
-createuser -P test
+    $ su - postgres
+    $ createuser -P test

 The following lines must be added near the end of the pg_hba.conf, corresponding to the three types of connection. They must be added on the table with the following columns: TYPE DATABASE USER CIDR-ADDRESS METHOD.

-local   all    test                              password
-host    all    test        127.0.0.1/32          password
+    local   all    test                              password
+    host    all    test        127.0.0.1/32          password

 Important: Each user-specific rule must be placed before a general case rule if you want this rule to apply. The specific IPv4 Djeen's rule has to be typed above the default rule for IPv4 local connections.

-host    all    test        127.0.0.1/32          password
-host    all    all         127.0.0.1/32          ident
+    host    all    test        127.0.0.1/32          password
+    host    all    all         127.0.0.1/32          ident

 The pg_hba.conf is located in /var/lib/pgsql/data (CentOS) or /etc/postgresql/8.4/main (Ubuntu). You could find it with:
-find /var -name pg_hba.conf; find /etc -name pg_hba.conf
-CGI scripts management
+    $ find /var -name pg_hba.conf; find /etc -name pg_hba.conf
+
+#### CGI scripts management

 Djeen file upload functionality uses Perl CGI. CGI scripts must be activated in your Apache configuration, if not already, and restricted to the Djeen tree. There are two ways of adding this information to the Apache configuration. Once done, restart the web server (see below).

 1) Specify a ScriptAlias:

-ScriptAlias /JOOMLA_URL_PATH/components/com_djeen/assets/cgi/ "/DOCUMENT_ROOT/JOOMLA_URL_PATH/components/com_djeen/assets/cgi/"
+    ScriptAlias /JOOMLA_URL_PATH/components/com_djeen/assets/cgi/ "/DOCUMENT_ROOT/JOOMLA_URL_PATH/components/com_djeen/assets/cgi/"

 Moreover, you could restrict PerlCGI execution to the Djeen component using the followings (untested):

-
-    AllowOverride None
-    Options None
-    Order allow,deny
-    Allow from all
-
+    
+        AllowOverride None
+        Options None
+        Order allow,deny
+        Allow from all
+    

 Which turns into:

-# Djeen section for Apache
-scriptAlias "/djeen/components/com_djeen/assets/cgi/" "/var/www/djeen/components/com_djeen/assets/cgi/" 
-
+    # Djeen section for Apache
+    scriptAlias "/djeen/components/com_djeen/assets/cgi/" "/var/www/djeen/components/com_djeen/assets/cgi/" 
+    
       AllowOverride None
-      Options None
-      Order allow,deny
-      Allow from all
-
+          Options None
+          Order allow,deny
+          Allow from all
+    

 or 2) To specify ExecCGI option:

@@ -259,15 +260,15 @@

 The same file must specify that the server is granted the right to execute CGI scripts located in Djeen CGI dedicated directory.

-
-    AllowOverride None
-    Options +ExecCGI
-    Order allow,deny
-    Allow from all
-
-
-    Restart
-    service httpd restart (CentOS) or service apache2 stop; sleep 10; service apache2 start (Ubuntu)
+    
+        AllowOverride None
+        Options +ExecCGI
+        Order allow,deny
+        Allow from all
+    
+
+Restart
+    $ service httpd restart (CentOS) or service apache2 stop; sleep 10; service apache2 start (Ubuntu)

 ### Directories configuration
 Files' storage permissions
@@ -278,27 +279,28 @@

 Either create the Djeen files root storage:

-mkdir /my_big_disk/djeen_1
-chown -r www-data.www-data /my_big_disk/djeen_1
+    $ mkdir /my_big_disk/djeen_1
+    $ chown -r www-data.www-data /my_big_disk/djeen_1

 either create the Djeen root storage:

-mkdir /my_big_disk/djeen            # Root of all needed disk access
-mkdir /my_big_disk/djeen/djeen_1    # Files storage
-mkdir /my_big_disk/djeen/log        # Log storage
-mkdir /my_big_disk/djeen/cache     # Cache storage
-chown -r www-data.www-data /my_big_disk/djeen
+    $ mkdir /my_big_disk/djeen            # Root of all needed disk access
+    $ mkdir /my_big_disk/djeen/djeen_1    # Files storage
+    $ mkdir /my_big_disk/djeen/log        # Log storage
+    $ mkdir /my_big_disk/djeen/cache     # Cache storage
+    $ chown -r www-data.www-data /my_big_disk/djeen

 Important: for security reasons, you are not allowed to define the data directories as subdirectories of the Djeen component. It is indeed better to separate the component engine from its data (Note: CGI directory isn't considered as a data directory).
-Joomla! sub-directories permissions
+
+### Joomla! sub-directories permissions

 This section could be skipped safely if you already changed the owner of Joomla! directory previously.

 Once Joomla! is installed, the Apache user and group are needed. They are specified in the httpd.conf file, as follows:

-User MY_APACHE_USER
-Group MY_APACHE_GROUP
+    User MY_APACHE_USER
+    Group MY_APACHE_GROUP

 The read/write/execute rights to the Apache user and group must be given to the following sub-directories of the website (chown -R MY_APACHE_USER:MY_APACHE_GROUP DIRECTORY_PATH on Linux). Otherwise, file copy in those directories could fail during the following component installation:

@@ -344,19 +346,20 @@
 #### Step 3: Data spaces configuration

 This section applies to both storages, database and files. The form has to be filled with the following values:
-Files directory    the path of the directory where the uploaded data files will be stored._(see above)_
-Driver     MySQL or PostgreSQL
-Host   localhost
-Port   3306 (default port for MySQL) or 5432 (default port for PostgreSQL)
-Base   the name of the Djeen database to be created
-User   the name of the MySQL / PostgreSQL user you created earlier
-Password   password of this user
+- Files directory  the path of the directory where the uploaded data files will be stored._(see above)_
+- Driver   MySQL or PostgreSQL
+- Host     localhost
+- Port     3306 (default port for MySQL) or 5432 (default port for PostgreSQL)
+- Base     the name of the Djeen database to be created
+- User     the name of the MySQL / PostgreSQL user you created earlier
+- Password     password of this user
+
 Note: if the installation bugs at the validation of this step, that's to say, depending if you desactivated the PHP display_errors parameter or not:

-    you just get a white screen
-    you get the undefined function mcrypt_encrypt() PHP error message (or something similar)
-
-It's due to the fact that you didn't install the prerequisites PHP libraires libmcrypt and php-mcrypt (see here).
+- you just get a white screen
+- you get the undefined function mcrypt_encrypt() PHP error message (or something similar)
+
+It is due to the fact that you didn't install the prerequisites PHP libraires libmcrypt and php-mcrypt (see here).

 #### Step 4: Installation summary

@@ -368,9 +371,9 @@

 If you want to change some parameters of the user access created above (like for example the menu in which it is displayed or its position in the menu):

-    Go into Menus => Main Menu
-    Click on the 'Djeen' menu item.
-    Make your changes, and save them.
+- Go into Menus => Main Menu
+- Click on the 'Djeen' menu item.
+- Make your changes, and save them.

 ### Finish

Installation modified by Ghislain Bidaut

Ghislain Bidaut — Mon, 02 Sep 2013 14:52:12 -0000

Djeen Installation Guide

Prerequisites

Version

This guide was written for Djeen version 1.5 and Joomla! 1.5.
System Requirements

Client

All the features have been validated for the following browsers:

Firefox 7+
Chrome 16+

Server

Unix OS

Apache server (on Linux: package httpd or apache2)

Perl version 5.x (required for the upload functionality, see below)

PHP version 5.3+
Several additional PHP libraries:
    libmcrypt
    php-mcrypt
    php-mysql
    php-pdo _(not available on Ubuntu, already integrated)
    php-pgsql (if PostgreSQL is chosen as Djeen database, see below)

Database management system(s): the Joomla! database requires a MySQL database, while the Djeen database can be either a MySQL base or a PostgreSQL base; so install PostgreSQL if you choose it for Djeen data storage.
    MySQL database system AND server (on Linux: packages mysql and myqsl-server)
    PostgreSQL database system AND server (on Linux: packages postgresql and postgresql-server)
    Optionally, phpmyadmin and pgmyadmin to get a Web user interface for those database engines.

Some disk space to store files

Note: installation was originally tested on Linux CentOS 5.5 and 6.0 operating systems; it has been adapted for Ubuntu/Debian also.
Perl and libraries

At last, the CGI.pm file must be checked for its presence on the server. This is the perl library managing CGIs.

Under Unix prompt, a locate CGI.pm will help to find out if the file exists somewhere on the server.
If the file is not present, it has to be installed either with the package manager, either with the cpan tool (or perl -MCPAN -e shell).

CPAN way:
On the first use, CPAN will ask for configuration. It is possible to simply answer yes at the first question to have CPAN configure itself automatically. Then, under the CPAN prompt, the CGI package can be installed with install CGI.
If there is an error during the installation process, an upgrade command is necessary. The CGI library can then be installed normally with install CGI.

Installation of required packages under Ubuntu 10.4

Packages should be named with their version. Required packages (except Perl) should be installed with a command like:

sudo apt-get install mysql-client-5.1 mysql-server-5.1 # Mysql
sudo apt-get install postgresql-8.4 postgresql-client-8.4 # Postgresql
sudo apt-get install libmcrypt4 php5-mcrypt php5-mysql php5-pgsql # PHP
sudo apt-get install apache2-mpm-prefork libapache2-mod-php5 # Apache
sudo apt-get install perl libcgi-pm-perl # Perl, CGI.pm

Check your set up
URL and PATH

The web server is accessed by use of its internet name (my_computer.my_company.fr) or its IP address (10.1.1.1). If you install a test instance, this might be localhost. Whatever name is chosen, it will be referred here as SERVER_NAME.

By default Apache provides access to documents located in the folder stated as DocumentRoot in its configuration. This folder corresponds to the root of the web server as seen from a user point of view, ie. http://SERVER_NAME/, which is the ROOT_URL of the web server. This folder varies on Linux distributions. It is either /var/www (CentOS), either /var/www (Ubuntu). The Apache configuration file is httpd.conf (CentOS) or /etc/apache2/sites-available/default (Ubuntu). It could also be found with: find /etc -name httpd.conf; find /var -name httpd.conf
Directory ROOT_URL
/var/www/ http://SERVER_NAME/
Web

Try connection to your web server: http://SERVER_NAME/
You should get the Apache 2 Test Page powered by CentOS (CentOS) or something like 'It works!' (Ubuntu).
Apache is working!

PHP

Add a php_info.php script to your document root:

echo ' <?php phpinfo(); ?> ' > /var/www/php_info.php

Connect to http://SERVER_NAME/php_info.php
You should get nicely formatted tables about your web server installation.
PHP is working! (you should remove this script)

Perl

Under the shell, type the command below:

perl -e 'use CGI; my $q=new CGI(); print "CGI OK!"'

It should not return any error.

Joomla! installation

URL and PATH

For sake of simplicity, Joomla! will be installed in the DocumentRoot tree in the following. You can either install Joomla! directory in the root or inside a sub-directory. Here is a directory/URL matching table supposing that DocumentRoot refers to /var/www :
Joomla directory ROOT_URL JOOMLA_URL JOOMLA_URL_PATH
/var/www/ http://SERVER_NAME/ http://SERVER_NAME/ /
/var/www/djeen/ http://SERVER_NAME/djeen http://SERVER_NAME/djeen /djeen

Create a specific directory for Djeen
cd /var/www
mkdir djeen

Download and unpack
First, Joomla! must be installed.

Download archives and installation instructions are found at http://www.joomla.org/.
(Instruction manual, if needed)

Code for English version, change the link for other language
wget http://joomlacode.org/gf/download/frsrelease/16914/73508/Joomla_2.5.4-Stable-Full_Package.zip
cd djeen
unzip ../Joo*zip

Important: For the moment, Djeen can only be installed on a Joomla! version 1.5 website, due to compatibility problems between Djeen and the most recent versions of Joomla! (1.6 and above).

Uncompress the downloaded Joomla! archive into a directory under the DocumentRoot. NB: the archive does not contain a root folder, so the files will be unzipped directly in the current folder.
Usually, it is recommended to set the owner of the unpacked tree to the user running the Apache daemon. This insures that the web interface will access the Joomla! tree. You will not have to modify permissions for any component later, because component will be installed with the Apache user.
You can find the real user running Apache with: ps -edf | grep apache
On Ubuntu, this user is www-data, and its group is www-data.

 Change the owner of Joomla! directory to apache user
chown -R www-data.www-data .

On-line guided installation

Joomla! installation is very well documented and you will be guided at each step, so you shouldn't encounter any notable difficulty. To start, just type the JOOMLA_URL into your web browser to begin the installation.

Below are a few more precisions of each step.
Step 2. Pre-installation check
In the Recommanded settings sub-section, if the Display Errors parameter is reported as 'On', you should:

go into your PHP configuration file (PHP.ini)
search for the line display_errors = On
set the value to Off
restart Apache server to have the new value taken into account
go back under your web browser and the Joomla! installation and click on the "Check again" button on the top right of the screen.

Letting the 'On' value will not cause any problem during the rest of the installation process. But once it's finished, the Joomla! website will have a very unpleasant display, with a LOT of warning messages, rending the navigation uncomfortable.
Step 4. Database configuration

You should only pay attention to the Basic settings sub-section.

A default configuration would be as follow:
Database Type MySQL
Host Name localhost
User Name root
Password password of the aforementioned user
Database Name joomla_db
Step 5. FTP configuration

Djeen doesn't need FTP, so you can skip this step and go directly to the next one.
Step 6. Main configuration

Example data are not needed, so just don't worry about the related sub-section if it's still checked.
Step 7. Finish

Once you have - as requested - deleted the 'installation' directory, click on the 'Admin' button on the top right corner of the screen to access the administration section of your Joomla! website. It's from there that you will install the Djeen component later.
Djeen installation
Outline
In this section, we will set up the storage environment for Djeen. Djeen stores data in two spaces:
a) the database space, in which objects are described are linked to files, and
b) the file storage itself, meaning that data files are external from the database. Here we will set up both spaces.

add a database user allowed to manage databases
update access to the database
add Perl CGI support to Apache
change permission (usually not needed)
set up storage

Database initialization

A new user must be created, with the following attributes:

NOT a super-user
allowed to create databases
with a password

In the following, we chose arbitrarily to name this user test (but could be also djeen).

Choice A) MySQL database

Under Unix prompt:

mysql -u root

create user test@localhost identified by 'TYPE_HERE_THE_PASSWORD_OF_TEST';

revoke super on . from test@localhost;

grant create on . to test@localhost;
grant alter on . to test@localhost;
grant select on . to test@localhost;
grant insert on . to test@localhost;
grant update on . to test@localhost;
grant delete on . to test@localhost;
grant drop on . to test@localhost;
grant lock tables on . to test@localhost;

Note 1: for the create user instruction, the password has to be typed between quotes.
Note 2: don't forget to mention the host (@localhost) after the user name.
Note 3: privilege lock tables is required to perform database dumps.

Alternative: Use PhpMyAdmin on the database server.
Choice B) PostgreSQL database

Under the Unix prompt (you might do sudo su to become super user first):

su - postgres
createuser -P test

The following lines must be added near the end of the pg_hba.conf, corresponding to the three types of connection. They must be added on the table with the following columns: TYPE DATABASE USER CIDR-ADDRESS METHOD.

local all test password
host all test 127.0.0.1/32 password

Important: Each user-specific rule must be placed before a general case rule if you want this rule to apply. The specific IPv4 Djeen's rule has to be typed above the default rule for IPv4 local connections.

host all test 127.0.0.1/32 password
host all all 127.0.0.1/32 ident

The pg_hba.conf is located in /var/lib/pgsql/data (CentOS) or /etc/postgresql/8.4/main (Ubuntu). You could find it with:
find /var -name pg_hba.conf; find /etc -name pg_hba.conf
CGI scripts management

Djeen file upload functionality uses Perl CGI. CGI scripts must be activated in your Apache configuration, if not already, and restricted to the Djeen tree. There are two ways of adding this information to the Apache configuration. Once done, restart the web server (see below).

1) Specify a ScriptAlias:

ScriptAlias /JOOMLA_URL_PATH/components/com_djeen/assets/cgi/ "/DOCUMENT_ROOT/JOOMLA_URL_PATH/components/com_djeen/assets/cgi/"

Moreover, you could restrict PerlCGI execution to the Djeen component using the followings (untested):

AllowOverride None
Options None
Order allow,deny
Allow from all

Which turns into:

Djeen section for Apache

scriptAlias "/djeen/components/com_djeen/assets/cgi/" "/var/www/djeen/components/com_djeen/assets/cgi/"

AllowOverride None
Options None
Order allow,deny
Allow from all

or 2) To specify ExecCGI option:

Search for the line AddHandler cgi-script .cgi in the Apache configuration.
If the line is commented (with character #), it has to be uncommented. If it's missing, it has to be added.

The same file must specify that the server is granted the right to execute CGI scripts located in Djeen CGI dedicated directory.

AllowOverride None
Options +ExecCGI
Order allow,deny
Allow from all

Restart
service httpd restart (CentOS) or service apache2 stop; sleep 10; service apache2 start (Ubuntu)

Directories configuration

Files' storage permissions

Djeen stores files and directories in its own tree. On a big disk, make directory that will be Djeen files root storage, then give full permission to the Apache user.
Djeen uses log and cache directories for some operations. You could choose to put those in the same tree instead of the component tree.
Because Djeen component creates automatically directories if they don't exist, you could choose the easy way of setting up a root storage only with full permissions to Apache user.

Either create the Djeen files root storage:

mkdir /my_big_disk/djeen_1
chown -r www-data.www-data /my_big_disk/djeen_1

either create the Djeen root storage:

mkdir /my_big_disk/djeen # Root of all needed disk access
mkdir /my_big_disk/djeen/djeen_1 # Files storage
mkdir /my_big_disk/djeen/log # Log storage
mkdir /my_big_disk/djeen/cache # Cache storage
chown -r www-data.www-data /my_big_disk/djeen

Important: for security reasons, you are not allowed to define the data directories as subdirectories of the Djeen component. It is indeed better to separate the component engine from its data (Note: CGI directory isn't considered as a data directory).
Joomla! sub-directories permissions

This section could be skipped safely if you already changed the owner of Joomla! directory previously.

Once Joomla! is installed, the Apache user and group are needed. They are specified in the httpd.conf file, as follows:

User MY_APACHE_USER
Group MY_APACHE_GROUP

The read/write/execute rights to the Apache user and group must be given to the following sub-directories of the website (chown -R MY_APACHE_USER:MY_APACHE_GROUP DIRECTORY_PATH on Linux). Otherwise, file copy in those directories could fail during the following component installation:

administrator
administrator/components
administrator/language
administrator/language/en-GB
administrator/language/fr-FR (if it exists)

components
language
language/en-GB
language/fr-FR (if it exists)

tmp

Add Djeen component in Joomla

Now you can install Djeen from the Administrator panel => Extensions => Install menu.

There are three different ways to install a component. The easiest one is the first ("Upload Package File"). Just select the Djeen archive and click on the "Upload File And Install" button.
Djeen (component) configuration

Click on the 'Start configuration' button and follow the steps to configure the component.

Each step is validated by the Next icon on the top right of the interface.

Step 0: License

Nothing to do here (except read, of course !).

Step 1: System check

Nothing to change here.

If a problem is reported concerning PHP or Perl modules, check that you have all the required libraires (here for PHP and there for Perl).
For PHP, keep in mind that the problematic extensions could be already installed, but simply not activated. In this case, don't forget to restart your Apache server after activating the concerned extensions.

Step 2: Directories configuration

The Cache directory and Log directory fields of the form must be filled. Default values state the Djeen component tree. If they don't already exist, they will be created. In this case, don't forget to grant the proper permissions on the parent directories in order to avoid error messages (usually already correct if permissions have been modified at Joomla! installation). If one or both directories already exist, you will get some warnings, but those won't block the configuration process. Nevertheless, you should also verify the permissions on those directories.

Step 3: Data spaces configuration

This section applies to both storages, database and files. The form has to be filled with the following values:
Files directory the path of the directory where the uploaded data files will be stored.(see above)
Driver MySQL or PostgreSQL
Host localhost
Port 3306 (default port for MySQL) or 5432 (default port for PostgreSQL)
Base the name of the Djeen database to be created
User the name of the MySQL / PostgreSQL user you created earlier
Password password of this user
Note: if the installation bugs at the validation of this step, that's to say, depending if you desactivated the PHP display_errors parameter or not:

you just get a white screen
you get the undefined function mcrypt_encrypt() PHP error message (or something similar)

It's due to the fact that you didn't install the prerequisites PHP libraires libmcrypt and php-mcrypt (see here).

Step 4: Installation summary

If you have a red cross next to the Cache directory or File directory field, it means either that one of these directory does not exist or that the permissions were not properly set.
You can create a user access for Djeen, by clicking on the 'Create' button in Front-end access section.

To finish the configuration process without creating the menu item, you MUST click on the Close icon on the top right of the interface.
Modify user access for Djeen

If you want to change some parameters of the user access created above (like for example the menu in which it is displayed or its position in the menu):

Go into Menus => Main Menu
Click on the 'Djeen' menu item.
Make your changes, and save them.

Finish

Click on the 'Preview' button on the top right corner to access Joomla!'s frontend. You should see the menu item you just created in the left part of the screen.