Installing DaPortal

Pierre Pronchery

Code and documentation. 

This guide was written for the DeforaOS project (and may be used by others).

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 3 as published by the Free Software Foundation.


Table of Contents

1. Introduction notes
1.1. Where to find DaPortal
1.2. Common requirements
1.3. Database backend
1.4. Hardening
2. Deployment as a web application
2.1. Additional requirements
2.2. Installation
2.3. Configuration
2.4. Database integration
2.5. Authentication
3. Deployment as a command-line application
3.1. Additional requirements
3.2. Installation
3.3. Configuration
3.4. Database integration
3.5. Authentication
4. Deployment as a Gtk+ application
4.1. Additional requirements
5. Additional configuration
5.1. Translations
5.2. Modules and users
5.3. Additional configuration values

Warning: work in progress

These notes are based on a development version of DaPortal 2.

1. Introduction notes

1.1. Where to find DaPortal

First, make sure that you have downloaded the latest stable version of DaPortal 2. It can be found there: http://www.defora.org/os/project/download/12/DaPortal. This guide will assume the resulting archive to be called DaPortal.tar.gz.

Alternatively, you may choose to track the development of DaPortal 2, or any given branch from the Source Code Management system. Some instructions to do so can be found here: http://www.defora.org/os/project/download/12/DaPortal.

1.2. Common requirements

DaPortal 2 is a Content Management System (CMS) written in the PHP programming language. It is based on a modular architecture, and therefore able to adapt to a number of different environments. It therefore requires a working installation of PHP, version 5.0 or later. PHP can be found at http://www.php.net/.

On many platforms the default installation of PHP does not include (or enable) all of the builtin extensions, some of which are required or recommended for DaPortal to function properly:

The following components are optional, and will likely improve the behavior of DaPortal:

  • the shared-mime-info package from the freedesktop project;

  • either one of the GNOME, Tango or XFCE4 icon themes.

  • the PHP PEAR modules for creating and decoding MIME messages, Mail_Mime and Mail_mimeDecode.

1.3. Database backend

DaPortal expects a database backend to be available to store and handle the data to be managed. A number of different backends are supported by DaPortal:

The actual choice is left to the administrator of the system. The corresponding PHP extension should be installed and enabled as well.

1.4. Hardening

The DaPortal installation is only as secure as its surrounding environment is; be sure to comply with best practices and the corresponding hardening guidelines for the system hosting DaPortal.

In particular, it is recommended to install and enable both the Suhosin patch and extension for PHP; please refer to http://www.hardened-php.net/suhosin/ for more information.

2. Deployment as a web application

2.1. Additional requirements

A web server supporting PHP is required for DaPortal to be deployed as a web application. DaPortal was most tested with Apache (versions 1.3 through 2.2), which is therefore the most recommended implementation. It can be found at http://httpd.apache.org/.

PHP's session extension is also required for session-based authentication to be functional.

2.2. Installation

For increased security, DaPortal 2 is meant to be installed in a separate directory, outside of the web server's document root folder. On most systems, this might be:

  • /usr/local/daportal for DaPortal 2;

  • /var/www/htdocs for the web server's document root.

This guide will assume these locations to be used in the following instructions.

Uncompress DaPortal 2 to the destination folder:

$ tar xzvf DaPortal-1.9.0.tar.gz
$ cd DaPortal-1.9.0
$ make install

You should then move, copy or alias the contents of DaPortal's data sub-directory in the web server's own document root folder. In the case of Apache, this might be done in the main configuration file, as shown in Example 1, “Data directory aliasing in Apache”.

Example 1. Data directory aliasing in Apache

Alias /css/ "/usr/local/daportal/data/css/"
Alias /icons/ "/usr/local/daportal/data/icons/"
Alias /js/ "/usr/local/daportal/data/js/"
Alias /themes/ "/usr/local/daportal/data/themes/"

Likewise, you may have to copy and modify the default index file, index.php, from the data directory to the document root. An example of such a file is found in Example 2, “index.php in the document root”:

Example 2. index.php in the document root

<?php if(chdir('/usr/local/daportal/src')) require('./daportal.php'); ?>

Be sure to set index.php as a valid index file in the web server's configuration (directive DirectoryIndex for Apache).

Alternatively, on most web servers it should be fine to serve DaPortal's own data folder as the actual document root (minding the index.php file).

2.3. Configuration

DaPortal has a single configuration file, daportal.conf, located within its own root folder. It is meant to be edited manually, and consists of a series of variable assignments (eg variable_name=the value), sorted within a number of sections (which names are surrounded by brackets, "[" and "]"). Comment lines are allowed as well, and begin with the "#" character.

DaPortal's HTTP engine should be selected automatically when PHP runs in the context of a web server. Otherwise (or for performance reasons) it is possible to enforce the appropriate engine by modifying the engine section of daportal.conf as follows:

[engine]
backend=http

The top-level theme and title settings can be changed as well, and will respectively define the default CSS to use (among the themes folder), and the default title for the web pages and documents generated.

Friendly links. Alternatively, DaPortal's HTTPFriendly engine can be selected. It can generate and handle HTTP links and requests that will typically be more readable, while also allowing better indexing of the different pages (eg for SEO, Search Engine Optimization). If available, it will normally take precedence over the default HTTP engine. It requires an additional parameter to be fully enabled, kicker, which designates an extra script to handle requests. The required configuration is illustrated here:

[engine]
backend=httpfriendly

[engine::httpfriendly]
kicker=somename

This configuration requires the following to work properly:

  • a handler called somename.php, placed along with the index.php file;

  • the web server must recognize this handler, and pass the incoming requests through it.

An example of such a handler is provided in Example 3, “Handler for friendly links”; in this case, it should be named somename.php and placed in the document root:

Example 3. Handler for friendly links

<?php
$_SERVER['SCRIPT_NAME'] = '/index.php';
require('./index.php');
?>

In the case of Apache, the following modification to the configuration for the document root may be necessary:

<Directory "/var/www/htdocs">
	Options MultiViews
	MultiviewsMatch Handlers
</Directory>
			

2.4. Database integration

The installation and configuration of the database engine itself will not be discussed here, as it is specific to each implementation. Its integration with DaPortal is however detailed here, taking SQLite 2 as an example.

The database backend to use must be specified in the database section of daportal.conf, as follows:

[database]
backend=sqlite2

[database::sqlite2]
filename=/var/www/sqlite/daportal.db

Additional parameters may have to be specified; see the respective database sections and documentation for reference. As shown here, in the case of SQLite 2 only filename is required in the [database::sqlite2] section, and points where the database file is found.

Such a database file can be created in /var/www/sqlite, as follows:

$ mkdir -p /var/www/sqlite
$ touch /var/www/sqlite/daportal.db
$ sqlite /var/www/sqlite/daportal.db
sqlite> .read /usr/local/share/doc/DaPortal/sql/sqlite.sql
sqlite> .quit

Warning: privileges for the SQLite database folder

Make sure that the web server has sufficient privileges to read and write to this database as required. In the case of SQLite, this often applies to the directory containing the database file itself (eg for locking).

With this last step done, DaPortal should now be ready to serve HTTP requests. If necessary, the authentication mechanisms in place can be modified; this is detailed in Section 2.5, “Authentication”.

2.5. Authentication

There are at least two ways available for DaPortal to authenticate users, when running as a web application:

  • http: performs HTTP basic authentication;

  • session: uses PHP's own session-handling mechanism.

The latter, session, is the most recommended and most tested authentication mechanisms of both. It should be selected by default by the engine when available. In any case, either can be enforced in the daportal.conf configuration file:

[auth]
#backend=http
backend=session

3. Deployment as a command-line application

3.1. Additional requirements

DaPortal provides a dedicated command-line utility, daportal, to issue requests to the system directly. For this to work properly, PHP must be installed with support for command-line applications (CLI).

For the default authentication mechanism to work correctly in command-line mode, PHP's POSIX extension is required as well.

3.2. Installation

The daportal command can be installed to the system as follows:

$ cd /var/www/daportal/tools
$ make PREFIX="/usr/local" install

Specifying the PREFIX value is optional, and defaults to /usr/local.

3.3. Configuration

It may be necessary to help the daportal script to locate the folder where DaPortal is installed; if available, the configuration file $PREFIX/etc/daportal.conf will be automatically read.

An example for this file is provided in Example 4, “Example of configuration file in $PREFIX/etc/daportal.conf” below:

Example 4. Example of configuration file in $PREFIX/etc/daportal.conf

DAPORTALDIR=/var/www/daportal

3.4. Database integration

Just like when installed as a web application, DaPortal needs a database backend to be configured when used as a command-line application. The instructions found in Section 2.4, “Database integration” apply here as well.

3.5. Authentication

Unlike the HTTP engine, the default authentication backend in use when running DaPortal on the command-line is unix. It maps usernames on the system to those found in DaPortal's database, which may therefore have to be edited manually beforehand.

4. Deployment as a Gtk+ application

4.1. Additional requirements

DaPortal 2 can also be used as a Gtk+ application. All of the requirements, installation, configuration and integration notes for DaPortal as a command-line application found in Section 3, “Deployment as a command-line application” therefore apply here.

Additionally, the Gtk+ extension for PHP is required; it can be found at http://gtk.php.net/.

5. Additional configuration

5.1. Translations

The user interface for DaPortal supports multiple languages through the GNU Gettext PHP extension. For this to work, the locale database for DaPortal must be installed; this can be done as follows:

$ cd /usr/local/daportal/po
$ make PREFIX="/usr/local" install

The value of PREFIX can be changed; in this case, the prefix variable in daportal.conf must be adjusted as well.

By default, DaPortal uses translation files from the current locale (if available). It can otherwise be forced in daportal.conf, as shown in Example 5, “Locale settings in daportal.conf”:

Example 5. Locale settings in daportal.conf

[defaults]
#for French
locale=fr_FR

5.2. Modules and users

Once the system functional, the modules enabled as well as user management can be performed directly through the administration interface, once logged as an administrative user.

The default credentials for a new installation are admin for the username, and password as the default password. It is strongly recommended to change the name for this user, as well as its password before using DaPortal in production.

5.3. Additional configuration values

The default configuration file also lists additional settings that may be applied to specific components. Please refer to its documentation for more information.