September 14, 2006

Create your own Planet

Author: Joe 'Zonker' Brockmeier

Major open source projects like GNOME, KDE, Ubuntu, Fedora, Debian, and Apache all have something in common -- they all have Planet feed reader sites set up to aggregate developer blog feeds. The Planet software was developed to power Planet GNOME and Planet Debian, but now it's being used by dozens of open source projects. With just a few simple steps, you can set up a Planet aggregator to watch your favorite blogs or to help publicize your favorite project.

The software, which is under the same license as Python, is available on the Planet home page. We'll set up the 2.0 release here, but you can also download a nightly snapshot if you prefer to live on the edge. Planet requires Python 2.2 or later, and the python-bdb package. Obviously, you'll also need Apache or another Web server as well to serve up your Planet pages.

After you've downloaded the Planet software, unpack the tarball under /var/www, or whatever directory you prefer. Planet comes with two default sets of templates under the examples directory -- basic and fancy. The basic theme is on the frumpy side, and I'm not aware of any live Planet sites using it, so you might want to use the fancy theme or take the time to customize templates for your own theme. Planet uses the htmltmpl templating engine; check that documentation if you're interested in customizing Planet. It shouldn't be too difficult if you're familiar with stylesheets and HTML.

Open the config.ini file in the theme directory of your choice and configure your Planet to your liking. You can customize the number of items per page, how many days' worth of entries, and other display options. The file is well-commented, so you shouldn't have much trouble getting Planet configured.

You may want to change the feed_timeout value if you're running Planet on a home network with a slow connection, or if you find that any of your feeds tend to time out regularly. The default is 20 seconds, which seems to work OK on my server.

Once you've set the defaults in the Planet section of the config, you can add your feeds. Each feed has a basic format of feed URL and feed name, like so:

[http://www.linux.com/index.rss]
name = Linux.com

Enclose the feed URL in brackets, and pass the name of the feed after name =. If you want your Planet site to use a hackergotchi image for each blogger, you'll need to specify the image file and its height and width if they don't match the default values in config.ini, like so:

[http://www.gnome.org/~jdub/blog/?flav=rss]
name = Jeff Waugh
face = jdub.png
facewidth = 70
faceheight = 74

If a blog has more than one author, but they're all aggregated in one RSS or Atom feed, choose an icon or logo for the site instead of one author's image.

The feed icons should live in the output/images directory -- so, if you unpacked the Planet tarball under /var/www and used the fancy theme under the examples directory, icons should be stored in /var/www/planet-2.0/examples/output/images. You can also replace the Planet logo file, logo.png, with your own logo if you want to.

Running Planet

After you have your feeds set up, you can run Planet with the following command in your top-level Planet directory:

planet.py path/to/config.ini

You should see messages about Planet processing the feeds after running planet.py the first time. After that, you can check your new Planet site at whatever URL the site lives at -- so if you've put it under your ~/public_html/planet (for example) just check the site at http://mysite.com/~user/planet/. Once you've made sure that everything is working properly, you can edit config.ini to crank down the logging by changing log_level to ERROR rather than DEBUG.

All that's left then is to set up a cron job to run planet.py on a regular basis, since you probably want your Planet page to update at regular intervals. I suggest running the job no more than once an hour -- you don't want to be pulling feeds from the aggregated blogs too often, and anything more than once an hour is probably a waste of bandwidth.

That's really all there is to it -- tweak the config file, add the feeds you want to use, and set a cron job to grab the feeds on a regular interval, and you've got your very own Planet.

Click Here!