Jose Castro, Bruno Martins - Perlbal documentation

Title: Perlbal documentation

Name: José Castro and Bruno Martins

Grant Manager: Makoto Nozaki

Duration: 2.5 months

Approved: August 2010



"It processes hundreds of millions of requests a day just for LiveJournal, Vox and TypePad and dozens of other "Web 2.0" applications."

It works great as a load balancer, wonderfully as a reverse proxy, marvellously as a web server.

If you know how to use it.

Perlbal lacks the documentation for even the simplest of tasks. Beginners can't possibly be expected to install and configure it by themselves, let alone write a plugin or accomplish some heavier task. At least not without losing some sanity.

However, all of these tasks are in fact easy ones.

But again, if you know how to do them.

This proposal aims at documenting several aspects of Perlbal and making several lives easier.

Benefits to the Perl Community

Grab a great Perl load balancing tool and make it usable to a broader audience.


Documentation detailing:

  • Installation
  • CookBook:
    • Using Perlbal as a reverse proxy
    • Using Perlbal as a load balancer
    • Using Perlbal as a web server
    • Managing and configuring Perlbal on-the-fly
  • Writing Plugins
  • Perlbal's Architecture at a glance

The resulting document should make non-Perlbal users able to install, configure and even write a Perlbal plugin without having to read Perlbal's code and/or bang their heads against a desk in the middle of the night.

This documentation will be written in POD, so it can be distributed along with the code. This will also allow for a quick conversion to Wiki format, so that the project page on Google Code can show the documentation on the web.

Project Details

We already got in touch with Alan Kasindorf (Dormando), one of Perlbal's main developers/committers/release managers, who told us "That'd be great."

Alan pointed out the desire to write documentation for Perlbal and also the lack of time on his behalf.

We'll keep in touch with Alan to make sure the resulting documentation is in conformity to what would be expected.


The project should take us 8 weeks, so we decided to detail some of the steps.

Also note that unless the Grant Committee advises us not to, we're keen on putting the documentation on a public github project from day one. It should also be noted that we intend on receiving the grant money even if other people start contributing to the project and aid us.

As soon as a chapter is completed, we can put it on Perlbal's homepage.

Week 1 - Installation procedures

We'll be installing Perlbal in a machine with barely anything on it (yes, we've done all these things before; several times).

We'll be documenting the process: all the steps, dependencies, requirements, problems we encounter and other possible problems we can think of.

This week should end with a document detailing everything a user needs to know to install Perlbal for the first time ever.

Week 2 - Load Balancer

Now we'll configure Perlbal as a Load Balancer.

Once again, we're going to be documenting all the steps taken.

The week should end with a document describing how Perlbal works as a Load Balancer, how to set it up, and containing examples for a few different setups.

Weeks 3 and 4 - Reverse Proxy and Web Server

More of the same.

More documentation, detailing all one needs to know to set up Perlbal as a Reverse Proxy or a Web Server, complete with a few recipes.

Week 5 - Managing and configuring Perlbal on-the-fly

During this week we'll be detailing how to check perlbal's status and how to configure it without restarting it.

Week 6 - Plugins

We'll be writing a couple of plugins.

The process will be documented and this should result in a document that will render any reader able to write their own plugin.

We'll also list the existing plugins out there, try some of them and describe how to use them.

Week 7 - Bonus Week

We'll be looking (once again) at Perlbal's architecture in order to detail it briefly to the curious user.

During this week we'll also be revising all the documentation written so far. That includes spell checking, grammar checking, content and recipes.

Project Schedule

Since our plan comprises 8 weeks, we're expecting it to take us 10.

It may look odd to an outsider, but we both have very demanding jobs where occasionally situations occur that require our attention after hours. That will leave us with very little time for this project and will end up delaying things.

It could also happen that we finish the project in 8 weeks, but our experience tells us we're better off with antecipating one rough week over the course of each month.

We'll still be aiming at the 8 weeks schedule, though, and doing our best to reach that target.

We can begin work on September 27th (this would make the end date December 6th).

Completeness Criteria

There will be documentation.

This should be readable, easy to understand, and contain instructions and examples on the following subjects:

  • Installation
  • CookBook:
    • Using Perlbal as a reverse proxy
    • Using Perlbal as a load balancer
    • Using Perlbal as a web server
    • Managing and configuring Perlbal on-the-fly
  • Writing Plugins
  • Perlbal's Architecture at a glance

We understand how readibility and ease of understanding are very subjective concepts, but this is a documentation project, so we feel those should be the criteria.

We considered having the completeness of the project being evaluated by having the documentation figure on Perlbal's wiki or source code, but since we know that other people have their own lives too we'd prefer a) not to depend on anyone else to have the grant being considered successful and b) not to thrust that responsibility on someone who has no responsibility towards the grant.


We're two Perl developers based in Lisbon. We work at SAPO - Portugal's largest web portal - where we make use of Perlbal in several projects.

We've both used Perlbal and wrote plugins for it (Bruno has managed to release one of them to CPAN).

We both have code on CPAN:

We're both regulars at Perl events:

And, most important of all, we have both suffered at the hands of Perlbal, and wish no one else to have to suffer too.

Links of interest

Project homepage -
Source code -
Wikipedia page -
Perlbal stuff on CPAN -