Menu ▾ ▴

Installation Guide

Ghislain Bidaut

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

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/

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

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/.

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 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.

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

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):

<Directory "/DOCUMENT_ROOT/JOOMLA_URL_PATH/components/com_djeen/assets/cgi">
    AllowOverride None
    Options None
    Order allow,deny
    Allow from all
</Directory>

Which turns into:

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

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.

<Directory "/DOCUMENT_ROOT/JOOMLA_URL_PATH/components/com_djeen/assets/cgi">
    AllowOverride None
    Options +ExecCGI
    Order allow,deny
    Allow from all
</Directory>

Restart with:

$ 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 is 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.

Related

Wiki: Home

MongoDB Logo MongoDB