In this blog entry I want to talk about the StatusNet server and how you can write plugins for it. In my practical work for the DSG I used StatusNet to write a basic Tweetflow Engine (specification) which handles variables and offers a restful interface.

StatusNet is an open source application written in PHP which offers functionality similar to social plattforms like Twitter.
So it is possible to build your own twitterlike plattform.
A major part of StatusNet is its plugin system which allows everyone to extend the server. There are already a bunch of plugins written by the maintainers and the growing community. For example there are plugins which enable to make (cross-) postings between your StatusNet plattform and other social networks like Facebook and Twitter. StatusNet has a lot of interfaces like XMPP or SMTP.

The first deployment of StatusNet was Identi.ca which is hosted by the creators of the StatusNet.

Installation

Now I want to show you the basic steps towards your own simple StatusNet plugin. First we need a running StatusNet instance. Since it is written in PHP and uses MySQL you should be able to run it on every basic web host. But for now I asume that you are going to install it on your local machine or on a dedicated server. I’m using Ubuntu Linux, so some of these steps may vary for other plattforms.

Webserver and Database

To run the StatusNet instance I installed the Apache 2 webserver (apache2) and the MySQL server (mysql-server) from the package repositories. Since we run a PHP application it is also necessary to install the Apache PHP module (libapache2-mod-php5) and for the MySQL connection we need the MySQL module for PHP (php5-mysql).

Configuring Apache

Creating a Virtual Host

The next step is to create a new virtual host. Of course, it is possible to install StatusNet directly into the document root of the webserver, but creating a virtual host is not difficult and a cleaner solution.

You just need to create a new file in the directory for the virtual hosts (eg. /etc/apache2/sites-available under Linux). I’ve created a file named “statusnet” with following content:

<VirtualHost *:80>
  ServerAdmin webmaster@localhost
  ServerName statusnet
  DocumentRoot /var/www/statusnet

  <Directory /var/www/statusnet>
    Options Indexes FollowSymLinks MultiViews
    AllowOverride all
    Order allow,deny
    allow from all
  </Directory>
</VirtualHost>

This creates a new virtual host which listens on port 80 and with a dedicated document root (/var/www/statusnet). For simplicity I’ve added the option “AllowOverride all”, so we could use the .htaccess-file provided by the StatusNet installation which enables the rewrite engine and some other settings. However, to increase the performance and security you should do this configuration in the virtual host file.

Now we have to enable the virtual host with a symbolic link in the “sites-enabled” directory or just by calling Apache’s utility script “a2ensite statusnet”.

Adding a New Host Entry

Because its only a local installation I used “statusnet” as the server name. Normally you enter the full domain name of your server (eg. www.example.org).
To simulate a installation on a public server we have to add a hostname to our hosts configuration file. In Linux you’ll have to add an entry to the “/etc/hosts” file, e.g.:

127.0.1.1 statusnet

With this entry we could later type “http://statusnet” into the browser and the server would serve us our StatusNet instance.

Enabling Rewrite Engine

There is one last basic configuration step of Apache:
We want to activate the rewrite module. When we do so, StatusNet is able to create nice and fancy URLs like “http://example.org/statusnet/fred” instead of “http://example.org/statusnet/index.php?p=statusnet/fred”. This is much more readable and further better for SEO.
To activate the module we could again use a helpful script. Just execute “a2enmod rewrite” in your console to enable it.

Restart Apache

Our Apache webserver is now configured and should be restarted to load all new settings and modules. In Linux there is usually a init-script that handles this, so we could execute something like “/etc/init.d/apache restart” in our console.

Configuring MySQL

StatusNet needs an existing database, so we have to create one. The simplest way is by using the mysqladmin-tool.
To create a new database “statusnet” execute the following line:

mysqladmin -u root -p create statusnet

You will be asked for the root-password which was entered during installation of the MySQL server.

We could use the “root”-user in our StatusNet installation, but since this is very bad practice and opens your database and server to successful attackers we create a new user for our StatusNet instance.
First we have to login with root:

mysql -u root -p

Now we could create a user “statusnet” and grant him access to our newly created database. Just enter the following line into the mysql-console:

grant all on statusnet.* to 'statusnet'@'localhost' identified by 'PASSWORD';

Of course you should use a complex password

Installing StatusNet

The actual installation of StatusNet is straightforward. We have to change to the document root of our virtual host (we’ve used /var/www/statusnet) and unpack the distribution from http://status.net.

Before we start the installation script of StatusNet, we have to rename the sample .htaccess-file (“htaccess.sample”) to “.htaccess”. It configures the rewrite engine to enable us nice URLs. One thing we have to change is the “RewriteBase” option and use “/” as the root path.

There are a few directories for which StatusNet needs write-access, like the directory for avatar files.
The easiest way is to set the group of all files to the webserver’s group and grant this group the permission to write those files. In the installation directory you have to execute:

chgrp -R www-data ./
chmod -R g+w ./

to change the group and it’s rights of all files.
Of course this is not the cleanest way because many files and folders don’t need to be writeable by the server.

Finally we can call the install.php script in our browser and thanks to our virtual host the url is very simple:

http://statusnet/install.php

Simply fill out all fields and don’t forget to enable the fancy url support.

Writing Plugins

Now as we’ve installed our StatusNet instance, it is time to write a simple plugin.

Usually every plugin has a main class which extends the Plugin class that comes with StatusNet. You have to place the class in one of these directories:

local/plugins/PLUGIN_CLASS.php
local/plugins/PLUGIN_NAME/PLUGIN_CLASS.php
local/PLUGIN_CLASS.php
local/PLUGIN_NAME/PLUGIN_CLASS.php
plugins/PLUGIN_CLASS.php
plugins/PLUGIN_NAME/PLUGIN_CLASS.php

For example the plugin class for the Tweetflow Engine has following path:

local/plugins/Tweetflow/TweetflowPlugin.php

Method Hooks

StatusNet offers a lot of method hooks to extend the functionality of the server system. There are basic hooks for initialization, cleanup, database installations and so on.

But the main logic will use the huge list of events to hook which you can find in the EVENTS.txt file in the root directory. Every event listed in this file could be intercepted by your plugin. The usage is very simple. If you have a event X with params P1 and P2 you simply write following method:

function onX($P1, $P2) {
  // your logic
}

Of course some params may be passed by reference, so you have to add a prefixed ‘&’.

For the Tweetflow engine I have to parse every message a user is posting, so the engine is able to determine if a post is a Tweetflow post. The proper event for this was the “EndNoticeSave”-event. As the documentation says it is fired after a notice is saved and therefore has a unique ID.
I simply inserted the following function into the Tweetflow plugin class:

function onEndNoticeSave(Notice $notice)
{
  // do Tweetflow engine related stuff
}

In the body of this function the parsing of the notice is done and if its a Tweetflow post the engine saves it into the database and offers it through the restful interface.

As you can see it is very easy to extend StatusNet with your own plugins.

Actions

Another important extension point are actions. Actions are mainly used for the frontend of StatusNet. There are a lot of events to hook and many output methods.

The Tweetflow engine uses actions to provide the simple restful interface. StatusNet offers many utility functions to ease the output of HTML, XML and JSON.

Starting With Plugin Development

If you want to write a plugin quickly, the best way is to copy, rename and extend the Sample plugin which StatusNet offers. You can find it in the plugins/Sample directory.
There is a lot of documentation in the files this plugin uses.

Another helpful source of information is the online Wiki:

http://status.net/wiki/Main_Page

Unfortunately the amount of information is limited and the progress of improvement is very slow. I recommend to use all written plugins if you need information about the usage of specific methods.

The End

I hope this blog post gives you a quick overview of StatusNet and helps to start developing plugins for it.

Stefan Hammer

Tags: Status Net Based Tweetflow Engine, StatusNet, Tweetflows