Lincoln Loop

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

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.

Comments

• December 18, 2009 at 12:59 p.m. #
  Peter Baumgartner added:

  In trying to figure out how to setup pro accounts, I stumbled upon the /ep/admin/ URL which has some interesting links.

  http://skitch.com/baumer/nc8wk/etherpad-admin

• December 28, 2009 at 2:51 p.m. #
  Trinitor chimed in with:

  Hi,
  I think
  etherpad-trunk/trunk/etherpad/src/globals.js
  should be
  etherpad-trunk/trunk/etherpad/src/etherpad/globals.js

• January 4, 2010 at 11:11 a.m. #
  Peter Baumgartner piped up:

  You’re correct Trinitor. I’ll correct that now.

  I’ll be trying out this fork next http://bitbucket.org/mattsta/etherpad-postgres/overview/. It has some fixes to make pro accounts work can use Postgres.

• January 5, 2010 at 11:48 p.m. #
  Paul mentioned:

  What is the performance like? I’ve been using Wave and I find it can be a bit doggy at times (even in Chrome). I see they have moved these guys into the Wave project at Google.

• January 8, 2010 at 3:18 a.m. #
  Marco Louro chimed in with:

  @Paul, performance is much better than wave at this point, but you can (still) create new pads (without registration) on http://etherpad.com and check it out.

• January 14, 2010 at 2:50 a.m. #
  Måns piped up:

  Hello,

  I am trying this out but failing at the rebuildjar step:

  > ./bin/rebuildjar.sh
  using JAR jar…
  cp: missing destination file operand after `lib/’

  The error seems to be in infrastructure/bin/makejar.sh which on line 23 attempts “cp ${MYSQL_CONNECTOR_JAR} lib/” but the mysql_connector_jar is undefined.

  Am I missing something obvious here?

• January 14, 2010 at 3:27 a.m. #
  Måns Jonasson added:

  Certainly, I was missing something obvious – the environment vars. Sorry ‘bout that.

• January 14, 2010 at 4:49 p.m. #
  Max responded:

  THX a lot for this nice tutorial!!

  works like a charm on my Ubuntu 8.04!

• January 28, 2010 at 11:29 p.m. #
  naveen kumar.talakokkula mentioned:

  Hi,

  Really helps me alot, thanks allot to guys.
  If you can provide these steps for the mac osx also, that would be great

  Thanks

• January 30, 2010 at 3:35 p.m. #
  Allison Sheridan responded:

  Like Måns I got stuck at the mysql_connector_jar is undefined but unlike Måns, I do not know what to set the environment variable TO. I’m a bit of a newb so go gentle on me?

• February 1, 2010 at 9:12 a.m. #
  Peter Baumgartner commented:

  Hi Allison,
  In your export.sh file, MYSQL_CONNECTOR_JAR should be the path to mysql-connector-java-5.1.10-bin.jar that you downloaded from http://ftp.plusline.de/mysql/Downloads/Connector-J/mysql-connector-java-5.1.10.tar.gz

  If you are still having issues, you might want to try the mailing list: http://groups.google.com/group/etherpad-open-source-discuss

• February 1, 2010 at 10:36 a.m. #
  Allison Sheridan commented:

  Thanks Peter, turns out the real problem was that the instructions at the bottom of step 2 say:
  “After that, load it via source exports.sh.”

  and since I’m a newb, I typed EXACTLY what it said, but it should be singular: export.sh

  because of that I hadn’t actually run export.sh so the environment variable wasn’t ever set.

  I’m off and running now!

  Thanks Marco for the instructions – you might want to fix that one typo.

• March 11, 2010 at 9:31 a.m. #
  Tobias McNulty chimed in with:

  Hey Pete – thanks for the nice write-up! You can also install the MySQL connector & Scala from APT – see https://wiki.ubuntu.com/Etherpad.

  In my case at least, a 256 meg VM was not enough; I had to upgrade to 512 before the thing would run. I’m running Ubuntu 9.10.

  Lastly, for a very simple/dumb init script that just starts the service on boot, on a Debian-based system, put the following in /etc/init.d/etherpad:

  #!/bin/sh
  
  ETHERPAD=”/path/to/etherpad/trunk/etherpad”
  
  if [ “x$1” = “xstart” ]; then
  
          cd $ETHERPAD
  
          bin/run-local.sh >> /var/log/etherpad.log 2>&1 &
  
  fi
  
  

  and then run:

  update-rc.d etherpad defaults
  

  to make it run at startup.

Got something to say?