Etherpad on Debian/Ubuntu

Since the release of Etherpad's source code last month and I have been really interested in studying the code and algorithm behind Etherpad's realtime editing.

Etherpad's backend is mostly written in Scala. Seeing how Scala is starting to be adopted by many popular online services, it's also worth looking into.

I thought I'd start off by installing my own instance of Etherpad. Unfortunately, the installations didn't quite work for me straight out of the box. After a few quirks, and with the help of this guide, I finally got Etherpad running. I am using Ubuntu 9.10, but the instructions should also work for Debian.

  1. Install Sun Java JDK
    apt-get install sun-java6-jdk

    Note: You need to have Sun's Java as your default. You can verify this by the following:
    java -version
    Java(TM) SE Runtime Environment (build X.X)
    Java HotSpot(TM) Client VM (build 14.3-b01, mixed mode, sharing)

    If you see anything other than what's above (for example, OpenJDK). You need to set Sun's Java as the default JDK. To do so, use the following command and follow the prompt.

    sudo update-alternatives --config java

  2. Install remaining prerequisites:
    apt-get install scala mysql-server libmysql-java mercurial
  3. Paste the following to /etc/profile, and be sure to replace X.X.X with the version of mysql connector that you have installed.
    export PATH
    export JAVA_HOME="/usr/lib/jvm/java-6-sun"
    export SCALA_HOME="/usr/share/java"
    export JAVA="/usr/bin/java"
    export SCALA="/usr/bin/scala"
    export PATH="/usr/bin:/usr/bin:/usr/local/mysql/bin:$PATH"
    export MYSQL_CONNECTOR_JAR="/usr/share/java/mysql-connector-java-X.X.X.jar"
    export JAVA_HOME SCALA_HOME JAVA SCALA MYSQL_CONNECTOR_JAR PATH
    umask 022
  4. Download the etherpad source to /usr/local/etherpad
    hg clone https://etherpad.googlecode.com/hg/ /usr/local/etherpad
  5. Set the environment variables: Again, remember to replace X.X.X with the corresponding version on your machine.
    export JAVA_HOME="/usr/lib/jvm/java-6-sun"
    export SCALA_HOME="/usr/share/java"
    export JAVA="/usr/bin/java"
    export SCALA="/usr/bin/scala"
    export PATH="/usr/bin:/usr/bin:/usr/local/mysql/bin:$PATH"
    export MYSQL_CONNECTOR_JAR="/usr/share/java/mysql-connector-java-X.X.X.jar"
  6. Add your domain to the superdomain section in /usr/local/etherpad/trunk/etherpad/src/etherpad/globals.js. If you will only be accessing it locally (through localhost), you don't need to do this.
  7. Create the etherpad mysql db and privileges:
    mysql -u root -p
    # enter your password when prompted
    create database etherpad;
    grant all privileges on etherpad.* to 'etherpad'@'localhost' identified by 'password';
    quit
  8. Compile the JARs:
    cd /usr/local/etherpad/trunk/etherpad/
    ln -s /usr/share/java /usr/share/java/lib
    bin/rebuildjar.sh

    Edit: As Mihira pointed out in comment #2, you may come across this error when compiling with the bin/rebuildjar.sh:
    Unable to establish connection to compilation daemon. Compilation failed.

    The problem maybe that the server’s hostname doesn't have a entry for 127.0.0.1 in the /etc/hosts file. In that case, add 127.0.0.1 to the /etc/hosts file and run bin/rebuildjar.sh again.

  9. Run the web server:
    bin/run-local.sh
    Note: If you are running a machine or a VM with little RAM, you might encounter this message:
    Error occurred during initialization of VM
    Could not reserve enough space for object heap

    If you see this error when you try to run the web server, it can be resolved by decreasing the size of the needed heap. Edit bin/run-local.sh and change the variable MXRAM from 1G to something smaller (256m should do the trick), then try running bin/run-local.sh again.

  10. That's it! You can access Etherpad locally on http://localhost:9000