by Mariano Guerra

Getting Started Guide for Developers

screencast

If you just want to watch someone else go through this demo, watch the screencast!

naming conventions

• pshb/PSHB = pubsubhubbub
• gae/GAE = Google App Engine
• things that start with "$" are bash commands
• things that start with "!" are important notes

before you start

to follow this guide you will need some tools installed on your system

• python 2.5 (to run the google app engine hub)
• subversion client (to fetch the pubsubhubbub code)
• git client (to fetch the example code)

this can be installed on a debian based distribution with a command like

sudo aptitude install python2.5 subversion git-core

on other distributions the command should be similar depending on the package manager.

create directory to hold all the content of this tutorial

$ mkdir pshb
$ cd pshb

download Google App Engine SDK

! pshb trunk needs the latest version of GAE (1.2.4 as of today) to work, but ! the download page display an older version

$ wget http://googleappengine.googlecode.com/files/google_appengine_1.2.4.zip
$ unzip google_appengine_1.2.4.zip

! GAE needs python 2.5 in order to work, if you have an older or newer version of python install python 2.5 (OS and distro dependent, wont be covered here)

download the latest version of pshb

$ svn checkout http://pubsubhubbub.googlecode.com/svn/trunk/ pubsubhubbub

start pshb

$ python2.5 google_appengine/dev_appserver.py pubsubhubbub/hub/

! note the python2.5 command

check that the hub started

type http://localhost:8080 on your browser, you should see something like:

Welcome to the demo PubSubHubbub reference Hub server!

download the example

# we will need to fetch the tubes library and the example that we will be using.
$ git clone git://github.com/marianoguerra/tubes.git

# now we will start the example

$ cd tubes/ihasfriendz/
$ python main.py

we should see something like:

 * Running on http://0.0.0.0:8081/
 * Restarting with reloader...

components used by the example

• werkzeug: http://werkzeug.pocoo.org
• jquery: http://jquery.com
• tubes: http://github.com/marianoguerra/tubes/tree/master
• pubsubhubbub_publish.py: from pshb
• feedformatter.py: http://code.google.com/p/feedformatter/

publish the feed to the hub

go to the following URL on your browser: http://localhost:8080/publish

on the Topic field enter: http://localhost:8081/atom/stream/_MYUSER_ and click publish

! if everything goes OK, then you wont notice anything on the page, that's ok, browsers act that way to 204 responses

! MYUSER is a placeholder for the user you will use to post notices on the test app later (for example http://localhost:8081/atom/stream/marianoguerra)

subscribing to the hub

go to the following URL on your browser: http://localhost:8080/subscribe

on the Callback field enter: http://localhost:8081/callback on the Topic field enter: http://localhost:8081/atom/stream/_MYUSER_ on the Verify token field enter something random like: iwantmahcookie

! MYUSER is a placeholder for the user you will use to post notices on the test app later (for example http://localhost:8081/atom/stream/marianoguerra)

click Do it

! if everything goes OK, then you wont notice anything on the page, that's OK, browsers act that way to 204 responses

create some content

go to the following URL on your browser: http://localhost:8081/files/index.html

post some content on the form, use the user you used as MYUSER

you can check that the item was posted going manually to http://localhost:8081/atom/stream/_MYUSER_, you should see an atom feed there

manually processing the tasks

when running the hub on the dev server we have to run the task queues by hand, to do that go to http://localhost:8080/_ah/admin/queues

on the Tasks in Queue column of the feed-pulls you should see a number different than 0 (that is the number of messages you created since the last execution of that task).

click on the feed-pulls link, there click on the run button.

when we run the feed pulls task, we tell pshb to fetch the feeds that have new content (the ones that did a post to the hub to inform that there is new content)

! on production hubs this tasks are done automatically

now we go again to the Task Queues page, there the event-delivery queue should have a number different than 0 (the number of messages that are pending to be sent to the subscribers), we click on the event-delivery and then we click on the run button.

when we run the event delivery task, we tell pshb to do a POST on every callback url registered for the feeds that were fetched on the feed-pulls task.

seeing it work

now that we created a feed, informed the hub that we had new content, the hub fetched the content and sent it to the callback, we want to see this content, for this go with your browser to http://localhost:8081/new-notices/, you will see the notices that pshb posted back to you the last time.

! if you refresh the page you will notice that the messages aren't there anymore, that's because the example stores the new messages in a Queue that is flushed when the request for new notices is made, in this way you can see only the new messages.

! the example stores all the information on global variables on main.py (this is to make the example simpler), so every time you change something on main.py and save the server will reload the changes and all the data will disappear.

for lazy people

#!/usr/bin/env sh

# create the example directory
mkdir pshb
cd pshb

CWD=$(pwd)
EXAMPLE=$CWD/tubes/ihasfriendz

wget http://googleappengine.googlecode.com/files/google_appengine_1.2.4.zip
unzip google_appengine_1.2.4.zip

svn checkout http://pubsubhubbub.googlecode.com/svn/trunk/ pubsubhubbub


# we will need to fetch the tubes library and the example that we will be using.
git clone git://github.com/marianoguerra/tubes.git

# now we will start the example

echo "run \"cd $EXAMPLE; python main.py\" on a shell to run the example"
echo "run \"cd $PWD; python2.5 google_appengine/dev_appserver.py pubsubhubbub/hub/\" on a shell to run the hub"