From Harmoni

Contents 1 Requirements 2 Installation Procedure 2.1 Dependencies 2.2 PHP Configuration 2.2.1 Compile Options 2.2.2 php.ini Configuration Settings 2.2.3 MySQL my.cnf Configuration Settings 2.3 General Concerto Installation Steps 3 A More Secure Installation 3.1 Install in a non-web-accessible directory 3.1.1 Directory Structure 3.1.2 Configuration Changes 3.2 Safe Mode 3.2.1 Script Ownership 3.2.2 Safe Mode Include Dir 3.2.3 Safe Mode Exec Dir 3.2.4 Temporary Files 4 Troubleshooting 4.1 "MySQL server has gone away" Errors 4.2 "convert" Errors

Requirements

Concerto requires a system with the following:

• Apache Webserver
• PHP version 5.2 or greater
• One of the following databases:
  • MySQL version 5.0 or greater
  • PostgreSQL
• The ImageMagick libraries.
• The following PEAR packages:
  • PEAR::DB - Needed by the OAI provider implementation.
  • PEAR::Archive_Tar - Needed for importing and exporting Assets.

Installation Procedure

Dependencies

1. Install Apache, PHP, and your database system. Ensure that they are operational.
2. Install ImageMagick
3. Install PEAR::DB:

   # pear install DB

4. Install PEAR::Archive_Tar:

   # pear install Archive_Tar

PHP Configuration

Compile Options

• --with-gettext
• --with-zip=
• --with-bzip2
• --with-zlib-dir=
• --enable-memory-limit

If you wish to generate thumbnails using PHP's GD libraries for JPG and PNG images, enable the following:

• --with-gd
• --with-jpeg-dir=
• --with-png-dir=
• --with-jpeg-dir=

As well edit the concerto config file concerto/config/imageprocessor.conf.php and enable GD usage:

$configuration->addProperty('use_gd', TRUE);
$configuration->addProperty('gd_formats', array('jpg', 'png'));

By default, ImageMagick is used to generate thumbnails for all image types.

php.ini Configuration Settings

These options will enable files up to about 100MB to be added to Concerto.

• memory_limit = 300M
• upload_max_filesize = 100M
• post_max_size = 100M

MySQL my.cnf Configuration Settings

These options will enable files up to about 100MB to be added to Concerto.

• max_allowed_packet = 100M

General Concerto Installation Steps

1. Download Concerto
2. Unzip the package in a web-accessible directory.
3. Create a database and user in your database system which Concerto will use.
4. Copy the concert/config/database_default.conf.php to concert/config/database.conf.php
5. Edit concert/config/database.conf.php and set the database host, database name, user, and password options to match those of the database and user you just created.
6. Point your browser at the directory in which you put concerto, i.e. http://localhost/concerto/.
7. Log in with the default administrator account, username: jadministrator, password: password
8. Change the password of the default administrator account, or create a new administrator account and delete the jadministrator account.

A More Secure Installation

As noted in the Concerto Security page, there are a number of Concerto design features that work together to provide security. To enhance the security of your Concerto installation, make the following changes to the general installation steps above:

Install in a non-web-accessible directory

Concerto is designed so that every PHP request goes through one web-accessible script, index.php. All other PHP files can and should live outside of a web-accessible directory to prevent attempts to begin application execution in an unintended place and bypass input validation. At the time of this writing we do not know of any security vulnerabilities of this nature in Concerto, but installing in a non-web-accessible directory helps to harden the system.

Directory Structure

For this example we will install Concerto in /usr/local/concerto-code/ and put symlinks in a web-accessible directory /usr/local/concerto-web/ with symbolic links to the needed files and directories in the concerto-code directory. The directory structure is below:

/usr/local/concerto-code/
	config/
	doc/
	icons/
	index.php
	install.txt
	javascript/
	LICENSE.txt
	main/
		harmoni/
		libraries/
		modules/
		polyphony/
	oai.php
	sampledata/
	themes/

	...

/usr/local/concerto-web/
	icons/		--> /usr/local/concerto-code/icons/
	index.php	--> /usr/local/concerto-code/index.php
	javascript/	--> /usr/local/concerto-code/javascript/
	oai.php		--> /usr/local/concerto-code/oai.php
	polyphony/
		icons/		--> /usr/local/concerto-code/main/polyphony/icons/
		javascript/	--> /usr/local/concerto-code/main/polyphony/javascript/
	theme_images/	--> /usr/local/concerto-code/themes/SimpleThemeBlack/images/
	viewer/		--> /usr/local/concerto-code/viewer/

With this directory structure index.php, oai.php, and viewer/index.php are the only PHP scripts accessible through the web-server.

• index.php - This is the main controller script. All concerto execution goes through here.
• oai.php - This script just sets a hard-coded module/action pair and then continues execution through index.php. OAI-PMH clients don't like extra GET parameters in their URLs, so this script works around that limitation.
• viewer/index.php - This is a very simple PHP script that uses PHP set a default theme and data-source for the Javascript Viewer application.

Configuration Changes

The following configuration changes match up with the directory structure above:

• concerto-code/config/gui.conf.php -

  define("LOGO_URL", MYPATH."/theme_images/logo.gif");

• concerto-code/config/libraries.conf.php -

  define("POLYPHONY_PATH", dirname(MYURL)."/polyphony/");

Safe Mode

In PHP 4 and 5, Safe Mode is a PHP configuration directive that attempts to solve a number of security issues, such as preventing the execution of unintended scripts. By its nature, the default settings of Safe Mode are very limited and several changes will need to be made to allow Concerto and other Harmoni-based applications to run under Safe Mode.

Script Ownership

All PHP scripts and working directories MUST be owned by the user the web-server runs as -- often wwwrun, httpd, apache, or nobody dependent on the OS distribution.

chown -R wwwrun:www concerto

Safe Mode Include Dir

Since Concerto uses the PEAR::DB and PEAR::Archive_Tar libraries, the directory containing these scripts (probably /usr/local/lib/php/) must be added to the safe_mode_include_dir directive in the php.ini.

Safe Mode Exec Dir

Concerto, through the ImageProcessor Harmoni library, makes a system call to the ImageMagick convert program in order to generate thumbnails. The directory containing the convert command must be added to the safe_mode_exec_dir directive in the php.ini.

In most default installations, ImageMagick lives in /usr/local/bin. While you could add /usr/local/bin to the safe_mode_exec_dir directive, this would allow PHP to make system calls to any executable in /usr/local/bin, not only convert. A more secure configuration would be to install ImageMagick to a different directory, such as /usr/local/concerto-support, so that you could then add /usr/local/concerto-support/bin to the safe_mode_exec_dir directive and only have the required programs executable by PHP scripts.

Add the location of the ImageMagic installation to Concerto's config/imageprocessor.conf.php file:

$configuration->addProperty('imagemagick_path', "/usr/local/concerto-support/bin");

Temporary Files

Rather than allow Concerto and other PHP scripts to write to the system-wide /tmp directory, you can create a custom temp directory for Concerto to use, and give the web-server-user ownership of it. This will prevent PHP scripts from writing to locations used by other parts of the system. For example, you could use a directory like /var/concerto-tmp

Add this temporary-directory to Concerto's config/imageprocessor.conf.php file:

$configuration->addProperty('imagemagick_temp_dir', "/var/concerto-tmp");

This directory can also hold Concerto's OAI resumption tokens by creating a sub-directory and adding it to Concerto's config/oai.conf.php file:

$config->addProperty('OAI_TOKEN_DIR', "/var/concerto-tmp/oai_tokens");

Troubleshooting

"MySQL server has gone away" Errors

If Concerto stores its files in a MySQL database, then the max_allowed_packet option on the server needs to be raised above its default limit of 1MB. Note that Concerto base64 encodes file data to make it binary-safe, at the expense of a ~33% increase in storage size.

"convert" Errors

The "convert" command is part of the ImageMagick package.