How To Install Chiara 0.19.0 PEAR Channel Server

PEAR consistently confuses the hell out of me. With its 1998-like appearance, CVS repository, and thin documentation, PEAR walks a fine line by being an actively developed project while appearing to have long-ago been abandoned (at least by any designers and pragmatists).

Details aside, PEAR has a load of useful aspects, including its powerful package installer which initially attracted me to it. In fact, in this arena, nobody can touch it - it's amazing. At its core, PEAR is simply a bunch of PHP classes. These classes are put together into different packages which you can then download to obtain different bits of functionality.

Installing Your Own Pear Channel / Server

There may come a time when you wish to distribute a piece of software. PEAR, via a PEAR channel, is a great option. Specifically, PEAR will automatically handle for any dependencies and packages can be upgraded as you release new versions. PEAR is complete with a PEAR Server package that will do most of the heavy lifting for you. Like most of PEAR, the resulting admin interface looks like it was made in 1998, but the software is solid and (so far) has performed well for me.

Chiara PEAR Server

The Chiara PEAR Server package is maintained by Greg Beaver. His original post (celebrating its 3-year anniversary in a few weeks) on how to install the server can be found at the link below. It's a great guide - but just a little date (it happens to all of us). Below, I try to address and prevent a few potential problems.

1. Download & Install PEAR

Even if you have PEAR installed already, it may be a good idea to install a fresh copy to a specific folder. This is especially true if you're doing this on a shared server. From the folder where you want to install PEAR:

wget http://pear.php.net/go-pear.phar
php go-pear.phar

Simply answer the following questions - you shouldn't have to change too much under a normal setup. If you're on a shared server and are worried about access to the temporary folders at /tmp, simply change these to some directory that you DO have access to. If unsure, just leave them be. If the installer has problems accessing these folders, it'll yell at you.

2. Install Chiara PEAR Server

At the time of this posting, the latest Chiara release is version 0.19.0. To install, we'll first CD into the bin directory where we installed PEAR. This ensures that we're installing the Chiara PEAR Server to the correct PEAR installation on our system. This won't be necessary for everyone, but it's a safe thing to do.

cd bin
./pear upgrade MDB2_Schema-beta
./pear upgrade --alldeps chiara/Chiara_PEAR_Server-0.19.0

3. Installing MySQL support

For my installation, I used MySQL as the database where all my package information will be kept. If you're using something else, the following instructions will need to be tweaked.

./pear install MDB2_Driver_mysql-beta

4. Configuring Chiara

To configure Chiara and finish your installation, run the following from the command line:

./pear run-scripts chiara/Chiara_PEAR_Server

You'll first have to enter your database information as well as an admin "handle" and a name for your channel. If everything goes correctly, the installer will initialize the MySQL tables and then ask you a series of additional questions about your PEAR channel.

Since a PEAR channel is nothing fancier than a website with special functionality, the Chiara server will need to install a series of web-accessible files to your PEAR channel's webroot. For instance, if I'm setting up my repository to be pear.thatsquality.com, then I'll need to enter in wherever the webroot for that subdomain resides. Don't worry about the directory existing, the installer will create it for you.

5. Visit your Channel (and fix paths if necessary)

You should now be able to visit your pear channel in a browser. If you've setup your channel to be accessible at pear.thatsquality.com, then goto pear.thatsquality.com/admin.php. This is the login screen for your admin interface where you'll do everything from create packages and manage maintainers to upload the actual releases. To login, use the username and password you setup in step #4.

If you opted not to modify your php configuration file during the PEAR installation (or you're on a shared server so you couldn't modify it), you may see the following error when visiting admin.php

If you see this error, you'll need to add in a line to your admin.php file. Open admin.php and make the top of your file look like this:

<?php
set_include_path('/path/to/your/pear/install/share/pear');

require_once 'PEAR/Config.php';
...

The new line of code comes right after the opening

If you surf over to your actual base channel address (e.g., pear.thatsquality.com), you won't see much. This is the frontend interface that the PEAR package installer will interface with when people install or upgrade your packages. That being said, there's really not supposed to be anything here that can be viewed by a normal web user. If you want to see at least some signs that your channel is alive, surf to the file channel.xml at your channel (e.g. pear.thatsquality.com/channel.xml).

Possible Errors

When I first tried to install Chiara, I had a heck of a time. Here are a few places where I tripped up.

This error probably occurs when running the command ./pear run-scripts chiara/Chiara_PEAR_Server. Basically, it means that Chiara is NOT installed. What? You're sure you installed it? Well, maybe not actually. When you installed Chiara (via some command like ./pear upgrade --alldeps chiara/Chiara_PEAR_Server-0.19.0) you certainly saw a whole bunch of words and installations taking place on the screen. Look closely, however, near the top of everything and you may find this:

chiara/Chiara_PEAR_Server requires package "pear/MDB2_Schema" (version >= 0.6.0)

In other words, PEAR installed a series of dependent packages, but didn't actually install Chiara because it couldn't acquire the required dependency MDB2_Schema. The most likely reason for this is that MDB2_Schema is beta, so your PEAR installer didn't automatically grab it. To solve this, do the following:

./pear upgrade MDB2_Schema-beta

Now reinstall Chiara and be on your way.

This error occurs after you've run ./pear run-scripts chiara/Chiara_PEAR_Server and setup your database configuration. Instead of happily installing your database schema, you receive this error. The most likely reason is that you don't have the proper MDB2 database extension installed. If you're using MySQL, run the following command to solve this (then retry your Chiara configuration):

./pear install MDB2_Driver_mysql-beta

By the way, I user the beta version here because, at one point, it was necessary. It doesn't appear to be necessary anymore, so you should be safe without the -beta at the end.

Last Words

If you're going to use a PEAR channel to distribute your software, you've made a good but tough choice. While nothing (I know of) rivals its package installer in the PHP world, it's also confusing to figure out and has a steep learning curve. That being said, I use it and depend on it, and I'm far far from being alone.

If you've gone this route, the next question you'll need to answer is "How do I create packages?". I'll save that question for another day.