There has been quite a bit of confusion recently due to the best resource for setting up a channel being located on Toby's blog, and now being quite a few versions out of date. First of all, let it be known that the PEAR_Server package located at pear.chiaraquartet.net has been superseded by the Chiara_PEAR_Server package at pear.chiaraquartet.net.[1]

This means that in order to set up your own personal channel, you need to take these steps:

Before you begin (preconditions):

You need:

• PHP 5.0.3 or newer (PHP 5.1.0 or newer is recommended)
• PEAR 1.4.3 or newer (all earlier versions have a security hole).
• a MySQL database and the mysql or mysqli extension enabled in php.ini
• a web site containing no underscores "_" in its name.
• shell access to your web site - this is essential

Even if your web site has a global PEAR, you will want to install a local copy.

To acquire PEAR, the easiest methods are

1. for PHP 5.1.0 and newer, download go-pear.phar and run php go-pear.phar
2. for other versions, download go-pear.php and run php go-pear.php

You should see a screen like so:

[ ~]$ php5 go-pear.phar

Below is a suggested file layout for your new PEAR installation. To
change individual locations, type the number in front of the
directory. Type 'all' to change all of them or simply press Enter to
accept these locations.

1. Installation base ($prefix) : /home/youruser/pear
2. Binaries directory : /home/youruser/pear/bin
3. PHP code directory ($php_dir) : /home/youruser/pear/share/pear
4. Documentation directory : /home/youruser/pear/share/pear/docs
5. Data directory : /home/youruser/pear/share/pear/data
6. Tests directory : /home/youruser/pear/share/pear/tests
7. Name of configuration file : /home/youruser/.pearrc

1-7, 'all' or Enter to continue:

After installation, run this command to make sure things are working:

~/pear/bin/pear -V

You should see something like "PEAR version 1.X.X" where X.X is the latest version (1.4.9 at the time of this entry).. You may want to create a soft link (ln -s) to this so that you can type ~/pear install blah instead of ~/pear/bin/pear install blah.

if you are running an earlier version of pear, then you should upgrade via normal techniques:

pear clear-cache
pear upgrade PEAR

NOTE: if you are running a REALLY old version of PEAR (1.3.3 or older), you need to run these commands:

pear upgrade PEAR-1.3.6
pear upgrade PEAR

Acquiring Chiara_PEAR_Server

This is easy. Using your preferred pear binary (either pear or ~/pear) run these commands:

pear channel-discover pear.chiaraquartet.net
pear upgrade chiara/Chiara_PEAR_Server

At this point, you should see something very similar to:

downloading Chiara_PEAR_Server-0.18.4.tgz ...
Starting to download Chiara_PEAR_Server-0.18.4.tgz (32,479 bytes)
.........done: 32,479 bytes
upgrade ok: channel://pear.chiaraquartet.net/Chiara_PEAR_Server-0.18.4
Chiara_PEAR_Server: Optional feature pearweb available (Public frontend for users to browse channel packages)
To install use "pear install chiara/Chiara_PEAR_Server#featurename"
chiara/Chiara_PEAR_Server has post-install scripts:
/usr/local/lib/php/Chiara/PEAR/Server/mysqlinstall.php
Use "pear run-scripts chiara/Chiara_PEAR_Server" to run
DO NOT RUN SCRIPTS FROM UNTRUSTED SOURCES

ALWAYS READ THE TEXT!! It may contain important error messages. If your PEAR installation is using a php4 binary, for instance, the installation will fail and tell you why (PHP version < 5.0.0). You can fix this by setting your php_bin to a php5 binary (like pear config-set php_bin /path/to/php5), but this should not occur if you've set up your PEAR correctly.

Next, you need to run the post-installation script. To do this, type:

pear run-scripts chiara/Chiara_PEAR_Server

Answer "yes" to all yes/no questions, and then the script will ask you questions about the database. If your mysql user does not have create permission, you must create the database prior to running the script. The post-install script will create and populate the necessary database tables, and will create the administrative backend. Once you have successfully run the post-installation script, we can continue with the next steps.

Configuring Chiara_PEAR_Server

First, try these steps to ensure that the post-installation script worked:

1. using an external database browser (phpMyAdmin or the like) verify that tables like "packages" "channels" "maintainers" "handles" and so on were properly created in the database
2. verify that your channel's document root contains "channel.xml" by browsing to http://yourchannel.com/channel.xml using any web browser such as FireFox.
3. verify that you can access the administrative frontend by browsing to http://yourchannel.com/frontend.php where frontend.php is the name you chose for the administrative frontend in the post-installation script. Log in

Creating a pretty frontend for your end-users

To set up a frontend, simply run:

pear upgrade chiara/Chiara_PEAR_Server#pearweb

This will install the frontend package Davey Shafik has written. This requires some configuration, so please read more about it at http://pear.crtx.org.

Creating a package/adding users

Before you can merrily start using your channel, you need to create a package and add users to it. This is a security feature. Although users in a release's package.xml will be automatically added, only a registered lead developer assigned to a package can release. This includes administrators. This feature is designed to prevent unauthorized releases of packages.

So, to get started, let's imagine you are creating a package named "Foo_Bar" and that your username is "joeshmoe". You will need to take these steps:

1. log into your administrative frontend as "joeshmoe" (http://yourchannel.com/frontend.php or whatever you've named it)
2. Click "Create a Package"
3. Fill in the necessary details
4. Save it
5. Under "Manage Packages" you will see "Foo_Bar (Maintainers)"
6. click "(Maintainers)"
7. Choose "joeshmoe" in the "New Maintainer" dropdown
8. Choose "lead" in the "Role" dropdown
9. Choose "yes" in the "Active Maintainer " dropdown
10. Click "Add Maintainer"

That's it! Now, let's upload a release.

Uploading a release

Once you have performed these steps, you should be good to go. To upload a release (make sure you use package.xml version 2.0 so you can specify your channel) click on "Upload a release" and upload it. If you have a problem, an error message will be displayed. Most common is "unknown channel yourchannel.com" This occurs when you fail to provide the correct path to your pear.ini or .pearrc in the post-installation script.

To determine the location of the pear script you wish to use, run:

pear config-show

and look for the bottom lines:

User Configuration File Filename /home/foobar/.pearrc
System Configuration File Filename /usr/local/etc/pear.conf

The file you want to use is the User Configuration File, "/home/foobar/.pearrc" in this case. The other common problem is forgetting to add yourself in package.xml. For our example user joeshmoe, you need to add this to package.xml:

Remotely testing your channel

To remotely test the channel, simply run these commands from a remote machine that is running PEAR 1.4.0 or newer (I assume "yourchannel.com" is aliased to "yourchannel"):

pear channel-discover yourchannel.com
pear upgrade yourchannel/Foo_Bar

That's it!

[1] PEAR_Server has been renamed Chiara_PEAR_Server for licensing reasons. Although it is the intention of the (super-busy) developers of the Chiara_PEAR_Server package to eventually propose this package to pear.php.net as an official package, until that time, it is best to prefix the name so that it is readily distinguishable as a non-pear.php.net-based package.