ResPear - REST interface to Pirum

ResPear adds a RESTful remote control to Pirum. Thanks to ResPear, you can add and delete remotely a PEAR package on Pirum servers. There is two ways to add a package: you can send the package in a compressed format (zip, tar, or tgz) or you can send a simple URL pointing to a package.xml on the Web (on GitHub for example). In addition, ResPear uses an apikey system to authenticate users on the RESTful service (used for add and delete features).

ResPear is opensource and is written in PHP. Its source code has been written by Thomas Picard during spring 2011, then Stéphane Gully and Nicolas Thouvenin submitted few patches. ResPear source code is hosted on GitHub.

You can freely test Pirum with ResPear here:

• Pirum server: http://demo.respear.net
• ResPear server: http://demo.respear.net/respear/
• ResPear demo apikey: respear:354f123b-7a75-f654-9153-0e15dc2f5b52

To add a tgz package with curl interface:

wget https://github.com/kerphi/ResPear/raw/master/tests/ExAppli-1.0.1.tgz
cat ExAppli-1.0.1.tgz | curl -u respear:354f123b-7a75-f654-9153-0e15dc2f5b52 \
                             -X POST --data-binary @- \
                             http://demo.respear.net/respear/

To add a package just with its package.xml link (is this example from GitHub):

curl -u respear:354f123b-7a75-f654-9153-0e15dc2f5b52 \
     -X POST \
     -H "X-URL: https://github.com/touv/plor/raw/master/package.xml" \
     http://demo.respear.net/respear/

To add a package from the Web but with a HTTP authentication:

curl -u respear:354f123b-7a75-f654-9153-0e15dc2f5b52 \
     -X POST \
     -H "X-URL: https://mysecure-svn-server/package.xml" \
     -H "X-URL-Auth: `echo -n 'login:password' | base64`" \
     http://demo.respear.net/respear/

To remove a specific package version:

curl -u respear:354f123b-7a75-f654-9153-0e15dc2f5b52 \
     -X DELETE \
     http://demo.respear.net/respear/ExAppli/1.0.1/

To remove all versions of a package:

curl -u respear:354f123b-7a75-f654-9153-0e15dc2f5b52 \
     -X DELETE \
     http://demo.respear.net/respear/plor/

This install procedure is dedicated to Debian but can be easily adapted. Installation steps are illustrated with the ResPear demo PEAR channel http://demo.respear.net but you'll have to adapt it to your case.

Firstly you have to install Pirum on your Web server because ResPear is based on Pirum:

• Pirum is a PEAR package himself, so first step is to install PEAR on your server:

  apt-get install php-pear
  pear channel-discover pear.pirum-project.org
  pear install pirum/Pirum-beta

• Pirum need a /var/www/pirum.xml description file:

  <?xml version="1.0" encoding="UTF-8" ?>
  <server>
          <name>demo.respear.net</name>
          <summary>PEAR channel ResPear demo</summary>
          <alias>respear-demo</alias>
          <url>http://demo.respear.net</url>
  </server>

• You have to build your PEAR channel:

  /usr/bin/pirum build /var/www/

• Then your channel is ready to deliver PEAR package: http://demo.respear.net

Now you can install ResPear:

• Download it and its dependencies:

  pear channel-discover pear.respear.net
  pear install respear/plor
  pear install respear/atomwriter
  pear install respear/rest_client
  cd /var/www/
  git clone git://github.com/kerphi/ResPear.git respear

• Configure it in /var/www/respear/config.php
• Create you first apikey here: http://demo.respear.net/respear/apikey/
• Then ResPear is ready to receive RESTful commands: GET, POST, or DELETE. Try it with curl and your apikey !

  wget https://github.com/kerphi/ResPear/raw/master/tests/ExAppli-1.0.1.tgz
  cat ExAppli-1.0.1.tgz | curl -u login:apikey \
                               -X POST \
                               --data-binary @- \
                               http://demo.respear.net/respear/

Notice: if you are French and your are using Debian servers, you should have a look to Pkgi software. Pkgi helps you to deploy multiple apache (or other things) servers on a single Debian server.

• To secure your ResPear server you have to restrict the respear/apikey/admin.php script because it can be used to blacklist or delete apikeys. Example: http://demo.respear.net/respear/apikey/admin.php
• When a user delete a package, for security reason, the package is not really destroyed. It is stored in attic directory so you can easily restore it. Example: http://demo.respear.net/respear/attic/
• Administrators should take care about attic directory size. Don't forget to clear it periodically using crontab or tmpreaper or other softwares.