Today we're officially launching three new Planet sites for the universe to enjoy ... at least those with an Internet connection. For those unfamiliar with Planet, it's a terrific RSS news feed aggregrator which downloads news feeds published by web sites and aggregates their content into a single combined web page showing the collective feeds in chronological order, latest news first. Planet Mac collects news from two dozen of the most well-respected Mac sites on the web while Planet Gadget focuses on late-breaking news about all your favorite new toys collected from more than a dozen worldwide sites. And, last but not least, for all you Superman buffs: Planet Daily, a site with all the latest (real) news headlines from around the globe. There are loads of other planet sites of interest. A long list is available at Planet Planet, the mothership. And, yes, there's even a Planet Asterisk®. Finally, for those of you lucky enough to have a Nokia 770 Internet Tablet, you'll be happy to know that virtually all Planet sites are Nokia 770-friendly. In fact, hitting the 150% zoom key gives you a perfect Big-Type read with no horizontal scrolling, the way eBooks oughta be but usually aren't. If you missed our review, the Nokia 770 is the best $350 travel companion imaginable ... well, almost.
This is where most press releases end. But today we're going to show you how to build your own Planet: add a Mac, one Python, a feed parser, a templating engine, and a domain. Mix and serve. Presto! Your own new Planet is born. While this project will run on a Windows or Linux machine, it's much more fun to build and maintain it on a Mac ... because it's a 30-minute project! About half of our readers don't (yet) have a Mac. Too bad! But there's still hope. You really don't have to live with viruses, trojans, root kits, adware, and other secret back doors into your system unless you just enjoy pain. Anyway, there's never been a better time to try a Mac. Can you spell Intel R-O-C-K-E-T? Our tutorials will get you up and running in no time with your own web server, mail server, MySQL and PHP servers ... at no additional cost. Take it from a guy that lived and breathed PCs for over 20 years: Come on Over from the Dark Side. You'll never look back! We haven't, and the learning curve is virtually non-existent. </end of rant>
Now, where were we? For our own Planet sites, we're actually maintaining them on three iMacs (Mac minis work just as well), and then we're uploading content once an hour through a cron job to our redundant WestNIC-hosted Linux servers for all the world to see. It's called bandwidth, and you'll need plenty of it if you tackle a project such as those we've bitten off today. Of course WestNIC is practically giving bandwidth away at the moment: 500 gigs a month with 10 gigs of permanent (backed up!) storage for under $10 a month. Wow! We've used WestNIC for well over a year now, and it's been flawless. That's quite a contrast from our three previous hosting providers, all of whom served up a nightmare about once every three months. The $8.95 deal probably expires in the next couple days so HURRY if you're interested. That price is less than 10% of the going rate from most reputable providers for this much bandwidth.
Where to Begin. The real trick to making the Planet software work is getting the right Python engine installed on your system. While both Mac OS X Panther and Tiger come with Python preinstalled, it's unfortunately an older version which lacks support for python-bdb, the critical component to achieve liftoff with Planet. So download MacPython 2.4.1 from here. Once you've downloaded the software, just install it as you would any other Mac application. Can you say double-click? If you're running Tiger, you'll also want to apply the installer fix which is explained on the web site. Finally, grab the latest nightly build of Planet from here. Once the tar ball decompresses on your desktop, rename the folder to planet just to keep things simple. Because of some privileges issues, the easiest way to get things working is to give everyone full rights to this folder. Open a Terminal window, switch to root access, and set the rights substituting your account name on your Mac for mine (in bold):
chmod 777 /users/wardmundy/desktop/planet
Be sure your Mac's web server is running (System Preferences->Sharing->Personal Web Server) and then create a web folder for your new Planet site using your account name, not root. Just issue this command:
Configuring Planet. Before you can actually test things out, we need to do a little basic configuration magic with Planet. From your desktop, double-click the planet folder, then the examples folder, then the fancy folder. Now Ctrl-Click on config.ini and choose Open With ... TextEdit. You'll need to modify a few sections of code. Starting at the top, you'll see a section that looks like this:
# Every planet needs a [Planet] section
# name: Your planet's name
# link: Link to the main page
# owner_name: Your name
# owner_email: Your e-mail address
name = Planet Schmanet
link = http://planet.schmanet.janet/
owner_name = Janet
owner_email = janet@domainname
In the name field, give your planet a name. In the link field, insert the fully qualified domain name for your planet. Fill in your owner_name and owner-email address, and you're all set. Now move down the page to new_feed_items and change the 2 to something like 30. This sets the number of items your application will download from each RSS feed. You can adjust all of this later depending upon your subject matter. Continue moving down the page until you get to output_dir. Change the existing output entry to the address of your new web site directory on your Mac: /library/webserver/documents/planet. Leave the remaining settings alone at least until we get a successful first run.
The final step is setting up the actual RSS feeds which will be supported by your Planet application. Scroll further down the page until you get to the last section which starts like this:
name = Scott James Remnant
face = keybuk.png
# pick up the default facewidth and faceheight
name = Jeff Waugh
face = jdub.png
facewidth = 70
faceheight = 74
If you haven't done so already, now it's time to figure out what you want to cover in your Planet application. It could be subject matter oriented. If you need some ideas, just scan the RSS Feeds available from the Washington Post. Or you may choose just to collect your favorite RSS feeds into a Personal Planet. If you're addicted to your Nokia 770 like we are, trust us when we say you'll never touch another news reader after you see the zoomed text display of a Planet site on your Internet Tablet. Once you figure out your site's contents, write down the names of the sites and the addresses of the feeds. Then you simply replace the examples in the config file with your own selections. For example, a Nerd Vittles entry would look something like this. You'll note that we've commented out the optional "face" which is reserved for a picture of the blog owner. If you decide to use faces, you'd also want to uncomment the facewidth and faceheight lines and insert the correct dimensions for the picture to speed up loading of the web page.
name = Nerd Vittles
#face = nerd1.png
# pick up the default facewidth and faceheight
#facewidth = 62
#faceheight = 80
When you complete all of your RSS feed entries, press Command-S to save your config file changes to disk.
Setting Up the Web Site. We don't need to do much construction work on the Planet web site since the Planet application will handle the heavy-lifting for us. We do, however, need to copy a few things to the web site directory. So open your web site directory with Finder (DefaultDrive->library->webserver->documents->planet). Then open the planet folder on your Desktop in a second Finder window. Now copy the images folder from output to the open planet web folder. Also copy the planet.css style sheet to your planet web folder. If you have a favicon.ico file for your new web site, put it in there, too.
Modifying the Look and Feel of Your Site. Don't do it now, but make a mental note that you can customize your Planet site in any way you desire. Just be sure you make a backup of the web site template before you make improvements. The template is in the /examples/fancy folder and is named index.html.tmpl. You can edit the file with any text editor including TextEdit, pico, and nano. If you use pico or nano, be sure to start up the editor with -w to avoid unexpected line wrap problems.
Taking Your Planet for a Spin. Ready for a test run? Drop down to a Terminal windows again, and switch to root access (sudo su). Switch to the planet folder on your Desktop using your account name, not mine (replace all of the bold entries). And then give it a whirl:
/usr/local/bin/python /users/wardmundy/desktop/planet/planet.py /users/wardmundy/desktop/planet/examples/fancy/config.ini
You'll get some feedback that looks something like the following although you won't have any cached data on your first run:
INFO:planet.runner:Loading cached data
INFO:planet:Feed http://www.popgadget.net/index.xml unchanged
INFO:planet:Feed http://feeds.gawker.com/gizmodo/full unchanged
INFO:planet:Feed http://mundy.org/blog/wp-rss2.php unchanged
INFO:planet:Updating feed http://www.bradsdeals.com/rss.cfm?c=6
DEBUG:planet:Items in Feed: 20
INFO:planet:Feed http://feeds.feedburner.com/ubergizmo unchanged
INFO:planet:Updating feed http://www.woot.com/Blog/Rss.aspx
DEBUG:planet:Last Modified: 2006-01-27T17:15:41+00:00
DEBUG:planet:Items in Feed: 20
ERROR:planet:Error 404 while updating feed http://gizmonews.com/wp-rss2.php
INFO:planet:Updating feed http://www.engadget.com/rss.xml net:Items in Feed: 40
INFO:planet:Updating feed http://techbargains.com/rss.xml
DEBUG:planet:Last Modified: 2006-01-27T17:00:12+00:00
DEBUG:planet:Items in Feed: 93
DEBUG:planet:Removed expired or replaced item http://www.techbargains.com/news_displayItem.cfm/57004
DEBUG:planet:Removed expired or replaced item http://www.techbargains.com/news_displayItem.cfm/56997
DEBUG:planet:Removed expired or replaced item http://www.techbargains.com/news_displayItem.cfm/56969
INFO:planet.runner:Processing template examples/fancy/index.html.tmpl
INFO:planet.runner:Processing template examples/atom.xml.tmpl
INFO:planet.runner:Processing template examples/rss20.xml.tmpl
INFO:planet.runner:Processing template examples/rss10.xml.tmpl
INFO:planet.runner:Processing template examples/opml.xml.tmpl
INFO:planet.runner:Processing template examples/foafroll.xml.tmpl
The object here is to get a clean run. The way to figure that out is to look in the first section above for lines that begin with the word "ERROR." These are processing errors in accessing the sites you specified for inclusion in your Planet site. What this usually means is that either a site you chose is down, or the address of the site is incorrect, or the format of the RSS feed is not yet supported by Planet. You won't find many of the latter since Planet supports most flavors of RSS feeds. In any case, these errors need your attention and should be fixed in or removed from your config file before you automate the data collection process. The second section of code above tells you whether Planet was successful in generating the documents for your web site. If you don't see errors here, then you should be able to access your site at http://localhost/planet/ using your favorite web browser.
Automating Your Planet Site. Once you get a successful run and get the errors resolved, you'll want to automate the data collection process. You don't want to have to manually run the planet python script every time you want to visit your web site. And, if you plan to offer the site to others, then it obviously needs to be kept current. Also, if you plan to publish your web site through a hosting provider or even .Mac, this also can be automated. First, you need a script. And then you need to tell your Mac to run it periodically by adding a crontab entry. Here's the runupdate script we use. And, yes, your Planet also produces RSS feeds which can be published by copying those files to your host provider as well as what's shown below. Look in /library/webserver/documents/planet for the names of the RSS feed files. To begin, create a text file in the planet folder on your Desktop and insert something like the following. Be sure to chmod 775 runupdate to make the script executable. And remember to always run your script as root, or it will fail. Don't run the script yet. We've got to move the planet folder on your Desktop first.
/usr/local/bin/python /users/wardmundy/planet/planet.py /users/wardmundy/planet/examples/fancy/config.ini
/usr/bin/ftp -in <<EOF
user username password
rename index.html index.php
There are several potential gotcha's above. First, make sure you are positioned in the planet folder on your desktop before running the planet python script as root. Second, use your account name in the bolded entries on the second and third lines above, not mine. Third, make sure you are running the correct version of python to execute the script because there now are two versions on your Mac. Providing the extended name for python solves this. Fourth, insert the domain name of your host provider in lieu of planetgadget.com and provide the account name and password that you use to gain FTP access to your site. The www entry is the directory location of the web pages on our FTP site. YMMV!
Our hosting provider supports both .html and .php web pages so we perform a little magic here. Before uploading the updated web page (index.html), we first must delete the old one. But, when we do that, we run the risk that someone will hit the site at the moment the page is gone. This would result in a 404 error, and no web page. Not good!. So, what we do is rename the page to index.php after first deleting the old index.php file. Then, if someone hits the page during the update, they will get the index.php page which displays (when there is no index.html page). And it will look exactly like index.html since it has no embedded PHP code and, in fact, is the older version of the identical page.
The final step in automating updates of your Planet web site is to add a crontab entry on your Mac so that the above script runs periodically during the day and night. Before we do that, open a Finder window with the default folder for your accountname. Then drag the planet folder into this directory. Be careful not to accidentally drag the folder inside some other folder already stored in your accountname folder. Now open a Terminal session, switch to root user access (sudo su), and add the following line to the bottom of the system crontab file (pico -w /etc/crontab). Note that there should be a single tab between each of the seven entries below. Delete the intervening spaces! If it lines up with the other entries in your crontab file, you've done it correctly. Then save your changes: Ctrl-X, Y, then press Enter.
01 5-20 * * * root /users/wardmundy/planet/runupdate
Be sure to use your account name instead of mine. This crontab entry runs the script at one minute after the hour between the hours of 5 a.m. and 8 p.m. If you wanted the script to run hourly all day and night, replace 5-20 with an asterisk (*). If you wanted the script to run once every four hours, replace 5-20 with */4. If you only want the script to run at certain hours, just replace 5-20 with a list of the hours separated by commas with no spaces. Enjoy your new Planet!
Coming Attractions. Later this week we'll clue you in to the first (ever) Valentine's gift-with-a-plug for the Little Mrs. that won't get you killed. Caution: YMMV Then next week we'll be hot on the trail of the new, new, new Asterisk@Home release! Come join us. It's free.
Other Asterisk Projects? For a list of our previous Mac projects, click here. For a complete catalog of our previous Asterisk projects, click here. For the most recent articles including those you missed over the Christmas and New Year's holidays, click here and scroll down the page.