Friday, April 2, 2010

Etherpad Open Source Installation Step-By-Step

Today I wanted to create a blog post documenting the steps necessary to create a Etherpad virtual machine in our organization.  This should work great for anyone else as well.  This article is a mix of instructions from Ubuntu documentations found here and here.  This Etherpad virtual machine was also built on VMware vSphere 4.0, so there are a couple of steps specific to that environment, but in previous testing, I know that the same process works just fine in VMware Fusion as well.

Virtual Machine Setup:

First thing to do is to create a new virtual machine and installing the OS.  We will be using Ubuntu 9.10 server and using the minimal virtual machine installation.  You can see in the picture below how you can get this installation option, it is under the modes section you can access by hitting F4.

Once you work through the installation of the OS which I won't go through here, you will be left with a very minimal Linux installation that we will then want to get brought up-to-date for the rest of the install.

Once you log in for the first time, you will want to make sure the system is up-to-date.  This is very important especially on ESX because there is a bug in the default Kernel that will not let you mount CD's which is necessary to install the VMware Tools.  The commands for doing this are below:

$ sudo apt-get update
$ sudo apt-get upgrade

This should get you the latest versions of everything installed by default.

You will then need to install three sets of packages that are required for the installation of VMware Tools.

$ sudo apt-get install build-essential linux-headers-$(uname -r) psmisc

Once these are installed, then you can ask VMware to install the tools, and you will complete the install by issuing the following steps.

$ mount /media/cdrom0
$ cd /tmp
$ tar xvzf /media/cdrom0/VMwareTools*.gz
$ sudo vmware-tools-distrib/ -d
$ rm -rf vmware-tools-distrib
$ umount /media/cdrom0

Once this has been done, I always install a couple of other packages to make it easier to administer the server.  These are optional, but I will keep them in the documentation in case you are interested.

$ sudo apt-get install openssh-server nano

This concludes the basic setup of the Virtual Machine.  Now we can move on to the specifics of setting up Etherpad on this machine.

Etherpad Installation:

The next thing we need to do for the process of install Etherpad is to install the dependencies that are required for this to run.  We will do that with the following command:

$ sudo apt-get install sun-java6-jdk scala mysql-server mysql-client libmysql-java mercurial

One thing to be careful of is that when you install the mysql server it is going to ask you for a password for the root user.  Make sure that you write this down or remember it so we can use it later in the process.

Next you will want to download the source code from Google.  I prefer to put all of this code in the /opt directory on your server, but I have been known to use the /tmp directory as well.

The following lines will get you all the source code necessary.

$ cd /opt
$ hg clone etherpad

You will then need to make some changes to this source code to get it to compile on Ubuntu, but I will try and simplify that as much as possible.

The first file you will need to modify is titled which can be found in /opt/etherpad/trunk/infrastructure/bin.  You will want to modify the file to make changes to two specific lines.  You can use the command below to open the file for editing.

$ sudo nano /opt/etherpad/trunk/infrastructure/bin/

On Line 35 of, you will want to change this:

JARFILES=`echo $SCALA_HOME/lib/scala-library.jar lib/*.jar lib/manifest`

Into this:

JARFILES=`echo $SCALA_HOME/scala-library.jar lib/*.jar lib/manifest`

Also, on line 39 you will want to change this:

$JAR xf $SCALA_HOME/lib/scala-library.jar

Into this:

$JAR xf $SCALA_HOME/scala-library.jar

You will see that in both cases you are strictly removing the /lib directory out of the path.

By using ctrl-o and ctrl-x in nano you will be able to save and close.

You will then need to add your server to /opt/etherpad/trunk/etherpad/src/etherpad/globals.js

$ sudo nano /opt/etherpad/trunk/etherpad/src/etherpad/globals.js

On line 30, you will want to add a couple of lines: (Of course changing and server.ip.address to match the name and ip address in your environment)

'': true,
'server.ip.address': true,

Again, ctrl-o ctrl-x to save your changes.  

You will now need to set a bunch of environment variables to make sure the code will compile correctly.

$ export JAVA_HOME=/usr/lib/jvm/java-6-sun
$ export JAVA="$JAVA_HOME/bin/java"
$ export SCALA_HOME=/usr/share/java    # or =/tmp – see above
$ export SCALA="$SCALA_HOME/bin/scala" # Shouldn’t it be =/usr/bin/scala ?
$ export PATH="$JAVA_HOME/bin:$SCALA_HOME/bin:$PATH"
$ export MYSQL_CONNECTOR_JAR=/usr/share/java/mysql-connector-java.jar

You have two more files to make changes to, and then we can run the compile and start the application.  For this modification, we need to make a couple of setup changes to the database script so that it will work correctly with your password you setup earlier.

$ sudo nano /opt/etherpad/trunk/etherpad/bin/

On line 22, add the following line:


Then on line 26, change:

echo "create database ${db};" | ${mysql} -u root

To this: (yourpass should be what you setup earlier)

echo "create database ${db};" | ${mysql} --user=root --password=yourpass

Also, change line 29 from this:

echo "grant all privileges on ${db}.* to 'etherpad'@'localhost' identified by 'password';" | ${mysql} -u root

To this: (again, yourpass should be what you setup earlier)

echo "grant all privileges on ${db}.* to 'etherpad'@'localhost' identified by 'password';" | ${mysql} --user=root --password=etherpad

Save the file with ctrl-o ctrl-x and then run it

$ cd /opt/etherpad/trunk/etherpad
$ sudo bin/

You will want to make one final change, and that is to change the default port to port 80 instead of port 9000 which is what is in the code by default.

$ sudo nano /opt/etherpad/trunk/etherpad/etc/

On line 11, change the listen port from 9000 to 80 so it looks like this:

listen = 80

Once you save the file, you can then build the application:

$ cd /opt/etherpad/trunk/etherpad
$ bin/

Once that completes, you can start the application:

$ bin/

That is it, if everything worked out correctly you should see the following screen:

Clicking on the big button will get you the interface you may have been accustomed to:

If you have any problems, or questions about this, please feel free to let me know.