How to start hacking on palava

Diving into an unkown complex project is hard. We want to help you getting started with palava and to understand the different parts of the project.  We start out with an architectural overview, then dive into each component and explain its purpose.  At the end we list the prerequisits to start development.

Anatomy of palava

The palava project consists of multiple parts which are repositories on our Github account. For more information about the parts, see the readme files in the respective repositories.


palava-client is a JavaScript library (actually written in CoffeeScript) allowing you to create video conferences with multiple participants. It offers an abstraction layer above WebRTC, workarounds for browser bugs and incompatibilities as well as standardized signaling using the palava protocol.


palava-machine is the server implementing the signaling used by the palava-client. It is implemented in ruby using EventMachine.


palava-portal is the web page running at You can also use it as an example on how to use the palava-client and base your own palava instance on it. It is written using CoffeeScript and AngularJS. The portal can be deployed as static files.


palava-hq is a Ruby on Rails app which receives newsletter subscriptions and feedback submitted from the palava-portal. You will propably not need this part of the project if you want to set up your own Palava instance.


palava-stats evaluates the anonymous statistics created by palava-machine. It also shows user feedback collected by palava-hq.


The instructions are written for unix-like systems (Linux, OS X, *BDS, …).

First you have to install ruby. For example using rvm:

curl -L | sudo bash -s stable rvm requirements rvm install 1.9.3 rvm use 1.9.3 --default

We make heavy use of bundler to handle the dependencies of the individual projects. To install it run

gem install bundler

The code is hosted on Github, so you will need git to check out the code. An account on Github will enable you to create tickets, fork the code and create pull requests.

Dev Setup

Let us get started by setting up everything you need to develop on palava. The steps below are aimed at deveolpers. If you want to provide a palava instance to end users please use the instructions from our last blog post.

The first thing we need is the signaling server:

git clone cd palava-machine bundle install

To run the palava-machine simply type:


The palava-machine will now provide the signaling through a websocket on port 4233.

The next step is installing palava-portal:

git clone --recursive cd palava-portal bundle install

palava-portal also includes palava-client as a git submodule. You can find it at source/assets/js/palava.

To test the web application we have to compile the coffeescript code to JavaScript, merge and uglify files, insert some user defined variables like the port of the websocket used by palava-machine and so forth:

export PALAVA_RTC_ADDRESS="ws://localhost:4233/" bundle exec middleman server

This command will do all the things mentioned above and start a web server on port 4567 distributing the resulting files. It will update the files whenever you change the source code.

You are now the proud owner of your very own palava development setup!

Get in touch

Please clone, modify, test, play around with the code. Subscribe to our mailing list and join our jabber chat room at

Creative Commons Lizenzvertrag