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

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:

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.

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.

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.

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:

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

Uncompress DaPortal 2 to the destination folder:

$ mkdir -p /var/www/daportal
$ cd /var/www/daportal
$ tar xzvf DaPortal.tar.gz
$ mv DaPortal-*/* .
$ rmdir DaPortal-*

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

Alias /css/ "/var/www/daportal/data/css/"
Alias /icons/ "/var/www/daportal/data/icons/"
Alias /js/ "/var/www/daportal/data/js/"
Alias /themes/ "/var/www/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”:

<?php if(chdir('/var/www/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).

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:

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:

<?php
$_SERVER['SCRIPT_NAME'] = '/index.php';
if(chdir('/var/www/daportal/src')) require('./daportal.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>
			

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 /var/www/daportal/doc/sql/sqlite.sql
sqlite> .quit

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

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

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

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.

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.

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:

DAPORTALDIR=/var/www/daportal

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.

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.

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

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 /var/www/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”:

[defaults]
#for French
locale=fr_FR

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.

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