Running your own Self-Hosted Etherpad Instance

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

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"

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;

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

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
};