Etherpad is an amazing real-time collaborative editor with a very low barrier for entry (no logins, no additional software, etc.). In case you missed it, Etherpad was acquired by Google and after a community uproar decided to release their code as open source under the Apache License 2.0.

We were excited to get it up and running for our own internal use. What follows is a step-by-step guide of how we proped it up on our development servers.

Caveats:

  1. We’re not Java guys, so if there is something we could be doing better, let us know.
  2. The default setup of Etherpad is RAM hungry. Make sure you have at least 256MB free before you get started.
  3. Our instructions are Ubuntu/Debian specific, but should be easy to translate to a different distribution.

Step 1: Get the Requirements

mkdir /opt/webapps/etherpad/ && cd /opt/webapps/etherpad/
sudo aptitude install sun-java6-jdk mysql-server
wget http://ftp.plusline.de/mysql/Downloads/Connector-J/mysql-connector-java-5.1.10.tar.gz
wget http://www.scala-lang.org/downloads/distrib/files/scala-2.7.7.final.tgz
tar -xvf mysql-connector-java-5.1.10.tar.gz
tar -xvf scala-2.7.7.final.tgz
hg clone https://etherpad.googlecode.com/hg/ etherpad-trunk

This sets up your application directory and installs the requirements. Note: Sun Java is required. Confirm you are using it with java -version.

Step 2: Setup your Environment

Create a bash script called export.sh that stores you system paths for everything Etherpad needs.

APP_DIR="/opt/webapps/etherpad"
export JAVA_HOME="/usr/lib/jvm/java-6-sun"
export SCALA_HOME="$APP_DIR/scala-2.7.7.final"
export JAVA="$JAVA_HOME/bin/java"
export SCALA="$SCALA_HOME/bin/scala"
export PATH="$JAVA_HOME/bin:$SCALA_HOME/bin:$PATH"
export MYSQL_CONNECTOR_JAR="$APP_DIR/mysql-connector-java-5.1.10/mysql-connector-java-5.1.10-bin.jar"

After that, load it via source exports.sh.

Step 3: Setup your Database

Create a MySQL database.

mysql -u root -p

CREATE DATABASE etherpad;
CREATE USER 'etherpad'@'localhost' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON etherpad.* TO 'etherpad'@'localhost' WITH GRANT OPTION;

Of course, you’ll want to use a secure password. Store your MySQL settings under etherpad-trunk/trunk/etherpad/etc/etherpad.localdev-default.properties.

Step 4: Build your Jar and Serve it

There are nice helper scripts provided to make this step happen.

cd etherpad-trunk/trunk/etherpad
./bin/rebuildjar.sh
./bin/run-local.sh

Assuming things went well, you should have your own Etherpad instance running at http://localhost:9000. Note: the port can be changed in etherpad-trunk/trunk/etherpad/etc/etherpad.localdev-default.properties.

Step 5: Pushing it Live

We already have Nginx running on port 80 of this server, so proxying to the application was trivial. You can find a basic Nginx proxy configuration here.

You’ll also need to append your domain to the SUPERDOMAINS variable in etherpad-trunk/trunk/etherpad/src/etherpad/globals.js. That will look something like this:

var SUPERDOMAINS = {
    'etherpad.mydomain.com': true,
    'localhost': true
};

These are quick-and-dirty instructions that clearly don’t result in a production-ready setup, but for a development sandbox it does the trick. For now, we took the easy way out and “daemonized” it by running it in a detached screen.

Have any tips or tricks on how to improve this setup? Leave a comment, we’d love to hear them.