Preparation

Application files

You should have received or downloaded a compressed archive containing the latest stable version of PhPeace.
This archive contains all necessary PHP scripts and classes, plus a number of other files such as shell scripts, localization files, graphic images, SQL scripts, CSS and XSL stylesheets, and many more.

PhPeace is contained in one directory, which is usually placed under your web server directories. However only two sub-directories are mapped to the 2 required virtual hosts (portal and admin interface).

The first command is to decompress the archive into the destination directory, which is supposed to be located in /var/www/myportal (/var/www is the default location for virtual hosts on Debian and Gentoo, other systems may place them under /home/htdocs or /home/vhost)

# mkdir /var/www/myportal# tar xzf phpeace.tar.gz -C /var/www/myportal

The Apache user should own all PhPeace files so that PhPeace can update itself and generate the static pages.
The user under which Apache is running varies depending on the Linux distribution.
On Debian-based Linuxes is www-data, on Gentoo / Centos / Red Hat is apache

Assuming a Debian system, the command to execute is

# chown -R www-data.www-data /var/www/myportal

For Gentoo / Centos / Red Hat

# chown -R apache.apache /var/www/myportal

Apache

You have to configure two virtual hosts; as discussed earlier, it is assumed the following hostnames

• www.mydomain.org for the portal
• admin.mydomain.org for the administrative interface

You should have already configured your Apache for Name-based virtual hosting listening on port 80.

NameVirtualHost *:80

This is a standard setting for running multiple virtual hosts on the same web server.
For further details please refer to the official Apache documentation page
http://httpd.apache.org/docs/current/vhosts/name-based.html

You need to relax security for the directories where PhPeace is served from.
A quick way to achieve this is to set the following in your Apache configuration.

<Directory /var/www/myportal>
 Options Indexes FollowSymLinks
 AllowOverride All
 Order allow,deny
 Allow from all
</Directory>

You probably already have a similar setting for other sites or for the default one.

Alternatively you may prefer to apply this directive in the specific PhPeace virtual hosts.
In general, PhPeace needs AllowOverride All as it creates its own .htaccess files.
It also needs the FollowSymLinks option as all binary files are kept in a single location and symbolic links are created whenever they're used.

Virtual hosts do not require particular settings

<VirtualHost *:80>
 ServerName www.mydomain.org
 DocumentRoot /var/www/myportal/pub
</VirtualHost>
<VirtualHost *:80>
  ServerName admin.mydomain.org
  DocumentRoot /var/www/myportal/admin
</VirtualHost>


After configuring the 2 virtual hosts, restart gracefully the Apache service (the following command is for standard Debian systems, it may be different on your distribution)

# /etc/init.d/apache2 reload

MySQL

You need to create a dedicated database for your PhPeace installation.
This operation is usually performed by root via command-line however you may use alternative tools and user accounts as far as you have database creation permissions.

Your MySQL client should default to utf8 encoding.
To be safe, we suggest to run the following command, which will enforce utf8 regardless of the default MySQL configuration. So login as root

# mysql -p

and execute

> CREATE DATABASE mydatabase DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci;

mydatabase stands for the name you assign to your database. You can change it at your choice

Optionally, you should also create a dedicated user account to isolate your database operations.
Login again as root

# mysql -p

And run the following commands

> use mysql;
> GRANT ALL PRIVILEGES ON mydatabase.* TO myusername@localhost IDENTIFIED BY 'mypassword';

It is assumed that myusername and mypassword are your new credentials. Change them at your choice

Pay attention to:

• specify the database (mydatabase.*) otherwise you will give global privileges
• specify both the username and the host (to exclude anonymous users and external connections)
• set the password: never leave it empty!

The above command will not grant global and administrative privileges, such as the GRANT one, as clearly stated by MySQL documentation.
At the same time, you will already grant some privileges that, even if not currently used, may be used in future PhPeace versions.
However, here are more details about the privileges currently required by PhPeace (you may skip this section and jump to the PHP one if you are not interested into these permission details):

• Required at global level
  • None
• Required at database level
  • ALTER
  • CREATE
  • DELETE
  • DROP
  • INDEX
  • INSERT
  • LOCK TABLES
  • SELECT
  • UPDATE
• Not required, but possibly used in the future
  • ALTER ROUTINE
  • CREATE ROUTINE
  • CREATE TEMPORARY TABLES
  • CREATE VIEW
  • EXECUTE

Hence a stricter approach could be to grant only the necessary privileges

> GRANT ALTER,CREATE,DELETE,DROP,INDEX,INSERT,LOCK TABLES,SELECT,UPDATE ON mydatabase.* TO myusername@localhost IDENTIFIED BY 'mypassword';

PHP

PHP directives are set in php.ini which is usually stored under /etc/php or /etc/php5

Depending on your environment, you may prefer to set these directives locally in your virtual host configuration instead of the global php.ini. However not all directives can be set in this way.
Please check the official PHP documentation at http://www.php.net/manual/en/ini.list.php

PhPeace Requirements

file_uploads
should be enabled, otherwise you will not be able to upload any files

short_open_tags
should be enabled as some PhPeace code is using it

Recommendations

date.timezone = CET
(for European time) to prevent time-zone errors

memory_limit
defaults to 128M, which should be good for most PhPeace tasks, however you may want to set it to a higher value such as 256M

safe_mode Off
safe_mode is considered a useless restriction. It does not protect from some serious problems and furthermore it is architecturally incorrect to address security problems at PHP configuration level in such a generic way. It will not be supported by PHP6 anyway.
However PhPeace can run with safe_mode on, if you really want to.

register_globals
must always be off; PhPeace does not need it. If some applications on your server need it, then they are poorly written and you should be very concerned about their security.

allow_url_fopen
should be off, as it may represent a security issue; PhPeace does not use it.

display_errors
should generally be disabled in production; PhPeace uses its own error handler and there is a debug setting in the configuration to display errors in case debugging in production environment is necessary (only for urgent cases). Therefore if you think you will never need to debug PhPeace in live installations, leave this off which is safer for all your applications.

However please note that PHP fatal errors cannot be trapped by PHP error handler. You may want to write fatal errors to a temporary log file (writable by Apache user) in order to analyze them.
In order to do so, you have to set:
log_errors = On
error_log = /tmp/php_errors.log

magic_quotes_gpc
should be disabled, it adds complexity to input filtering and it is not database-specific; PhPeace does not need it but can cope with both settings.

open_basedir
restricts files that can be opened by PHP; PhPeace does not need it, but if you are in a shared-hosting environment, for security reasons it may be better to avoid that other applications can access PhPeace files. Keep in mind that open_basedir has an impact on performance, and in any case it's not 100% safe.
Furthermore, if you set open_basedir, pay attention to set a proper value for upload_tmp_dir otherwise file uploads will fail. Finally, remember not to exclude your PEAR installation directory for inclusions

upload_max_filesize and post_max_size should be set to allow large file uploads (20M is a reasonable value, but you may prefer a different setting)

MTA (Mail Transport Agent)

PhPeace needs to be able to use a mail relay to deliver administrative and user messages.
Usually a Linux installation has some MTA running on the localhost and relay email to external recipients. However this may vary a lot depending on your system and network configuration.

PhPeace tries to rely on the default PHP mail command, which will talk to the local sendmail process.
Alternatively you may run other MTAs such as postfix, exim and qmail.

If you don't have a local MTA, you can still use PHPMailer (embedded in PhPeace) to connect to a remote SMTP host. This is configured in PhPeace settings.