Primary image for Running your own Self-Hosted Etherpad Instance

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.


  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
tar -xvf mysql-connector-java-5.1.10.tar.gz
tar -xvf
hg clone etherpad-trunk
This sets up your application directory and installs the requirements. <em>Note: Sun Java is required. Confirm you are using it with java -version.</em>

Step 2: Setup your Environment

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

export JAVA_HOME="/usr/lib/jvm/java-6-sun"
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

Step 3: Setup your Database

Create a MySQL database.

mysql -u root -p
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/

Step 4: Build your Jar and Serve it

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

cd etherpad-trunk/trunk/etherpad
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/

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:

'': 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.
Marco Louro

About the author

Marco Louro

Marco is an Frontend developer, mostly focused in JavaScript, but with a wide range of interests and a background in various web technologies. He's been with Lincoln Loop since 2008. He first learned about Django in …

Marco is no longer active with Lincoln Loop.