Wave Reference Server - A Startup Guide

*** Edit the information contained here is out of date. To find more up to date information please visit here: http://wavingtheshiny.collaborynth.com.au/books/fedone-book/fedone-book ***

When Google announced the new Wave technology at the IO conference earlier this year they made a promise. That not only would the Protocols be Open, but they would also be Open Sourcing  "the Lions Share" of the code they were developing for the Wave.

Up until recently, that amounted to Robot and Gadget code, however true to their word, Google has released the first version of their Wave Reference Server under the Apache License. The instructions below will take you through the process of installing that server.

Please note: These instructions have been written for Ubuntu Jaunty, however I think we a little jigging around can be used for other distros.

What is the Wave Reference Server:

The Wave Reference Server is Googles first release of the code  behind their Wave server offering. Written in Java, it offers developers a chance to get into the guts of the Wave system and better understand how it works.

As well as the Server itself, the WRS comes with a Text based Wave Client. It is very rudimentary at the moment, however as with the Server it's an opportunity to see how exactly the Server and Clients communicate with each other. This can then be used to build other more featureful clients.

Requirements:

• Google Protocol Builder
• Sun Java SDK 6
• Openfire XMPP Server
• Mercurial
• Wave Server Reference Source

Before we start I recommend creating a directory specifically to hold everything we're going to need.

$ mkdir wave-devel

$ cd wave-devel

Once you're in the wave-devel directory run the following:

$ sudo apt-get install mercurial

$ sudo apt-get install sun-java6-jre sun-java6-fonts sun-java6-jdk

$ wget http://protobuf.googlecode.com/files/protobuf-2.1.0.tar.gz

$ hg clone https://wave-protocol.googlecode.com/hg/ wave-protocol

$ wget  http://www.igniterealtime.org/downloadServlet?filename=openfire/openfire_3.6.4_all.deb

Step 1: Building the Google Protocol Builder

[Edit: Anthony has told me that the WRS comes with an already generated set of Protocol files, so this step isn't strictly necessary, however for completeness I'm going to leave it in.]

Google has its own format for building serialised data streams and the WRS relies heavily on this technology. So before the Wave Server can be built you need to download and install the Google Protocol Builder. To do this, simply run the following commands:

$ tar -zxvf  protobuf-2.1.0.tar.gz

$ cd protobuf-2.1.0

$ ./configure --prefix=/usr

$ make

$ sudo make install

Step 2: Getting and Building the Wave Source

Now that you have the Google Protocol Builder installed you can move onto building the WRS itself.

First things first of course, grabbing the source. Move back into wave-devel and run the following:

$ cd wave-protocol

As I mentioned above, the WRS relies on the Google Protocol Builder tool to build the wire protocols into a format it can recognise and use. To do this, you need to do the following.

build-proto.properties

The build-proto.properties file contains the information that is going to be required to build the protocols. You need to edit this file so that it contains the following:

"protoc_dist=../protobuf-2.1.0" (this is assuming that you're working in the wave-devel directory we setup earlier. Otherwise simply put the full path to the protobuf directory in).

Now run the following:

$ ant -f build-proto.xml

This compiles the protocol into a format that can be used by the WRS. Once you have completed this stage you can move onto building the Server proper. This is a difficult and arduous process and requires the following commands:

$ ant

Umm yup, that's all it takes. If all goes well you should end up with four jar files in the dist directory.

• fedone-client-console-0.2.jar
• fedone-0.2.jar
• fedone-agent-echoey-0.2.jar
• fedone-api-0.2.jar

The first is the basic command line Wave client and the second is the Wave Server itself.

Step 3: Building the Certificates

The Federation protocols rely on each server being certified to some extent. For the moment we're going to be dealing with self signed certs however you can use certs from any provider. Below is a script I've pinched from Googles own Certification documentation

#!/bin/sh                                                                       

NAME=$1

if [ "$NAME" == '' ]
then
  echo "$0 <certificate name>" 1>&2
  exit 1
fi
openssl genrsa 1024 | openssl pkcs8 -topk8 -nocrypt -out $NAME.key
openssl req -new -x509 -nodes -sha1 -days 365 -key $NAME.key -out $NAME.cert

Run this script and fill it out as you would any other self signed cert. However when it comes to Common Name, ensure you use the dns entry you will be using to represent the Server.

Well, there we go, we're 90% of the way there. We're missing one component though. The WRS is not a standalone XMPP server (the Federation protocol itself is XMPP through and through). Instead it relies upon an external XMPP server to do the hard work. For this example we will be using the Openfire XMPP server, however if your XMPP server supports external components (XEP-0114 Components to be specific) then it should work.

Step 4: Installing and Setting Up Openfire

Installing Openfire is a pretty easy thing to do, run the following from the wave-devel directory:

$ sudo dpkg -i openfire_3.6.4_all.deb
$ sudo /etc/init.d/openfire restart

To test that Openfire is up and running, open up a browser and try to browse to http://localhost:9090. You should be presented with the start of the Installation wizard. Sticking with the defaults for this part of the process should be fine. Just remember to put the domain you want to use when asked. Then restart the server:

$ sudo /etc/init.d/openfire restart

In order to make Openfire support the WRS, you need to make a few changes once the server is up and running.

Enabling External Components:

Once the server has restarted, if you closed the browser open it up and login again the admin console on http://localhost:9090. Once you've logged in, do the following:

Server -> Server Settings -> External Components

In the External Components Management Page you need to make the following changes:

Service Enabled -> Switch to Enabled

                        -> Port should be 5275

                       -> Secret can be whatever you like

Allowed To Connect -> add a new subdomain called wave and a secret

Security:

Now go to Server -> Server Settings -> Security Settings.

Server Connection Security -> select "Custom"

Server Dialback ->  Select Available

Accept self-signed certificates -> Select the checkbox

Once that is done, browse to Server -> Server Settings -> Registration and Login and do the following:

Disable "Inband Account Registration".

Disable "Change Password".

Disable "Anonymous Login"

Enable server-server compression in "Compression Settings"

Disable file proxy transfer in "File Transfer Settings"

Disabling Group Chat and Pubsub

Through a bit of debugging I and Mark Achee discovered that the OpenFire XMPP server tends to be a little random in how it lists the services that it has on offer. By default it offers the Pubsub and Group Chat facilities as well as the Wave service that we've just setup. This can result in Federation issues as the chatter will be delivered to the wrong service. To ensure that this doesn't happen, it's best to disable Group Chat and Pubsub.

Disablilng Pubsub:

To disable the Pubsub service do the following:

Browse to Server Manager->System Properties. Scroll down to the bottom and enter the following information:

Property Name: xmpp.pubsub.enabled

Property Value: false

Disabling Group Chat:

Browse to Group Chat->Group Chat Settings.

Delete the conference domain.

Once you have completed these steps I find it best to restart the Openfire service (sudo /etc/init.d/openfire restart under ubuntu).

And there you have it. Now we should be able to start the WRS and start our new Wave Server experience.

Starting the Server and Client:

To start the client or server you first need to do the following:

$ cp run-config.sh.example run-config.sh

You will now need to edit your run-config.sh file and fill out the following variables:

WAVE_SERVER_DOMAIN_NAME=[YOUR_ROOT_DOMAIN]

WAVE_SERVER_HOSTNAME=[YOUR_ROOT_HOSTNAME]

WAVE_SERVER_PORT=9876

XMPP_SERVER_SECRET=[YOUR SECRET]

PRIVATE_KEY_FILENAME=[NAME].key

CERTIFICATE_FILENAME_LIST=[NAME].cert

XMPP_SERVER_IP=[IP_ADDRESS]

Once you've filled out these details, starting the client or server is pretty simple:

$ run-server.sh

or

$ run-client-console.sh [YOUR USERNAME]

Well that's it for the moment, hopefully by now you have a working server and client and you can start having a play around. Next time I'll be talking about setting up the Federation part of the server.

I would like to thank everyone who's worked on the Wave at Google and specifically Joe Gregorio, Anthony Baxter and dtbently for their documentation (which I've stolen chunks of for this).