After being acquired by Google, Ether­Pad was open­sourced. Being it the kick­ass thing it is, I got itch­ing with the *need* to have my own ether­pad instance run­ning right away.

As I found out, scratch­ing that itch was actu­ally fast: it took me ~3 or so hours, and that includes trou­bleshoot­ing and gath­er­ing bits of info from all around. With a step-by-step how-to it’ll prob­a­bly take you a lot less than that!

The machine was naraka.pauleira.com, run­ning Cen­tOS 5.3. I used YUM to install most of the pre­req­ui­sites from RPM repos­i­to­ries, but you’ll prob­a­bly be fine if you fol­low sim­i­lar steps with APT or while installing from source pack­ages. Probably! ;)

The machine serves http://pauleira.com, and I got Ether­Pad to answer on http://pauleira.com:9000 and https://pauleira.com:9001. Ether­Pad Pro account’s sub­do­mains are cre­ated as subdomains.pauleira.com and are like­wise avail­able at http://subdomain.pauleira.com:9000 and https://subdomain.pauleira.com:9001.

Let’s get started!

Cre­ate the ether­pad user

adduser -r -m etherpad

Set the DNS for *.yourdomain.com

For my pauleira.com domain, I just added a * A record in the DNS point­ing to the machine’s IP address. That’ll catch everything!.pauleira.com! If that gets you puz­zled, check wikipedia’s entry on the Wild­card DNS record for a gen­tle explanation.

Java

On Cen­tOS this is lit­tle bit more con­vo­luted than it should. Still, just fol­low the instruc­tions on http://wiki.centos.org/HowTos/JavaOnCentOS and you should reach the other side of the maze safe and sound:

# java -version
java version "1.6.0_11"
Java(TM) SE Runtime Environment (build 1.6.0_11-b03)
Java HotSpot(TM) Client VM (build 11.0-b16, mixed mode)

Scala

Got it from here.

# su - etherpad
# wget http://www.scala-lang.org/downloads/distrib/files/scala-2.7.7.final.tgz
# tar xfz scala-2.7.7.final.tgz

This will place your scala on

/home/etherpad/scala-2.7.7.final/

We’ll get back to that later on.

MySQL

# yum install mysql-server

and we need mysql to run, so:

# service mysqld start

If you never launched the mysqld before, it’ll warn you about the need to set a pass­word for the root account. I sug­gest you heed the warn­ings and do so!

Now is also a good time to add mysql as a ser­vice, so you don’t have to enable it man­u­ally every your machine restarts.

# chkconfig mysqld on

Now, to install some pre­reqs we’ll need to make some addi­tional repos­i­to­ries avail­able to YUM. If you don’t have them con­fig­ured yet, don’t worry, just fol­low the well-trodden path explained on each of these repos­i­to­ries’ links.

We need:

# yum install mysql-connector-java

which is pro­vided by the jpack­age repository.

IPTABLES

We’ll have Ether­Pad lis­ten for

• HTTP on port 9000
• HTTPS on port 9001

So we need those ports open in the machine’s firewall.

Check if ipt­a­bles is run­ning. As user root:

# service iptables status

If it is, then save the cur­rent rules

# service iptables save

Add the fol­low­ing rules before the COMMIT line in /etc/sysconfig/iptables

-A RH-Firewall-1-INPUT -p tcp -m state --state NEW -m tcp --dport 9000 -j ACCEPT
-A RH-Firewall-1-INPUT -p tcp -m state --state NEW -m tcp --dport 9001 -j ACCEPT

And then restart it:

# service iptables restart

Mer­cu­r­ial .. or Git

You can get Ether­Pad from from the off­i­cal repos­i­tory, on Google Code, where it uses Mer­cu­r­ial, but if you already have git and don’t want to install mer­cu­r­ial just for that, I’ve got a mir­ror you can use.

Both Git and Mer­cu­r­ial are pro­vided by DAG or RPMFORGE.

Once you get one of these going, just issue

# yum install mercurial

or

# yum install git

We’re now done with the pre­reqs, and it’s about time we dive in the dough!

Ether­Pad

I won’t digress about how cool Ether­Pad is. If you’re fol­low­ing this I sup­pose you’ve found that out already! :) After the acqui­si­tion by Google, EtherPad’s source code was (fit­tingly) hosted on Google Code.

This is where we’ll get it: Ether­Pad Open Source Release, the offi­cial repos­i­tory, by the EtherPad.com guys.

To check it out, with mercurial:

# su - etherpad
# hg clone https://etherpad.googlecode.com/hg/ etherpad

These check the repository’s code into etherpad’s homedir.

NOTE: for this tuto­r­ial we’ll leave the direc­tory hier­ar­chy as it is. How­ever, should you ever move “/home/etherpad/etherpad/trunk/etherpad”, some­where else, make sure you take “/home/etherpad/etherpad/trunk/infrastructure” there too, main­tain­ing both in the same hier­ar­chy level. You need both to com­pile EtherPad!

sslkey­store

Required for HTTPS. I used key­tool as below. It should be obvi­ous that STOREPASS_CHANGEME and KEYPASS_CHANGEME are to be replaced with some good and strong pass­words, as usual…

# su - etherpad
# cd etherpad/trunk/etherpad/data/appjet
# keytool -genkey -alias appjet -storepass STOREPASS_CHANGEME -keypass KEYPASS_CHANGEME -keyalg RSA -keystore sslkeystore

To know about what’s stored in a key­store file, use

# keytool -list -v -keystore sslkeystore

Now every­thing is in place, and we can con­fig­ure our Ether­pad instance.

Quick intro­duc­tion to diff files, as used here

diff -u /tmp/before /tmp/after
--- /tmp/before 2009-12-23 20:37:05.000000000 -0200
+++ /tmp/after  2009-12-23 20:37:40.000000000 -0200
@@ -1,5 +1,5 @@
 not changed not changed
 not changed not changed
-this line will be removed
-this line will be removed too
+this line was added
 not changed not changed
+this line was added in the end of the file

Make sure you under­stand the diff above before proceeding.

Really.

Ok, let’s get to work:

./etc/etherpad.localdev-default.properties

Copy the sam­ple con­fig file

# su - etherpad
# cd etherpad/trunk/etherpad
# cp etc/etherpad.localdev-default.properties data/etherpad.local.properties

And make the fol­low­ing changes

--- etc/etherpad.localdev-default.properties    2009-12-21 02:15:03.000000000 -0200
+++ data/etherpad.local.properties      2009-12-23 19:25:18.000000000 -0200
@@ -1,14 +1,16 @@
 ajstdlibHome = ../infrastructure/framework-src/modules
 appjetHome = ./data/appjet
-devMode = true
-etherpad.adminPass = password
+devMode = false
+etherpad.adminPass = ADMINPASS_CHANGEME
+smtpServer = localhost:25
 etherpad.fakeProduction = false
-etherpad.isProduction = false
+etherpad.isProduction = true
 etherpad.SQL_JDBC_DRIVER = com.mysql.jdbc.Driver
 etherpad.SQL_JDBC_URL = jdbc:mysql://localhost:3306/etherpad
-etherpad.SQL_PASSWORD = password
+etherpad.SQL_PASSWORD = MYSQLPASS_CHANGEME
 etherpad.SQL_USERNAME = etherpad
-listen = 9000
+listen = 0.0.0.0:9000
+listenSecure = 0.0.0.0:9001
 logDir = ./data/logs
 modulePath = ./src
 transportPrefix = /comet
+sslKeyPassword = KEYPASS_CHANGEME
+sslKeyStore = ./data/appjet/sslkeystore
+sslStorePassword = STOREPASS_CHANGEME

Pay atten­tion to the *_CHANGEME! :)

NOTE: These set­tings will get Ether­Pad to send emails by con­nect­ing to a mail trans­fer agent lis­ten­ing on localhost:25. If you need dif­fer­ent set­tings, check this.

And now a a num­ber of scat­tered changes:

./bin/setup-mysql-db.sh

--- ./bin/setup-mysql-db.sh.orig  2009-12-23 20:59:15.000000000 -0200
+++ ./bin/setup-mysql-db.sh       2009-12-23 20:59:31.000000000 -0200
@@ -25,6 +25,6 @@
 echo "create database ${db};" | ${mysql} -u root

 echo "Granting priviliges..."
-echo "grant all privileges on ${db}.* to 'etherpad'@'localhost' identified by 'password';" | ${mysql} -u root
+echo "grant all privileges on ${db}.* to 'etherpad'@'localhost' identified by 'MYSQLPASS_CHANGEME';" | ${mysql} -u root

 echo "Success"

./src/main.js

--- ./src/main.js.orig  2009-12-23 14:31:05.000000000 -0200
+++ ./src/main.js       2009-12-23 14:31:54.000000000 -0200
@@ -269,7 +269,7 @@
   }

   // redirect to etherpad.com
-  var newurl = "http://etherpad.com"+request.path;
+  var newurl = "http://YOURDOMAIN_CHANGEME.com"+request.path;
   if (request.query) { newurl += "?"+request.query; }
   response.redirect(newurl);
 }

./src/templates/pro/admin/admin-template.ejs

--- ./src/templates/pro/admin/admin-template.ejs.orig   2009-12-23 15:40:15.000000000 -0200
+++ ./src/templates/pro/admin/admin-template.ejs        2009-12-23 15:40:27.000000000 -0200
@@ -16,11 +16,9 @@
 <div class="fpcontent">
   <table id="admin-layout-table">
     <tr>
-      <% if (validLicense) { %>
         <td width="1%" id="admin-leftnav">
           <%= renderAdminLeftNav() %>
         </td>
-      <% } %>
       <td width="99%" id="admin-right">
         <%= getAdminContent() %>
       </td>

./src/templates/framed/framedheader-pro.ejs

--- ./src/templates/framed/framedheader-pro.ejs.orig    2009-12-23 14:39:11.000000000 -0200
+++ ./src/templates/framed/framedheader-pro.ejs 2009-12-23 14:39:37.000000000 -0200
@@ -64,10 +64,8 @@

 <div id="pro-topnav">
   <div id="pro-topnav-inner">
-    <% if (validLicense &amp;&amp; account) { %>
       <%= renderProTopNav() %>
       <%= helpers.clearFloats() %>
-    <% } %>
   </div>
 </div>

./src/static/crossdomain.xml

--- ./src/static/crossdomain.xml.orig   2009-12-23 15:34:54.000000000 -0200
+++ ./src/static/crossdomain.xml        2009-12-23 15:44:46.000000000 -0200
@@ -3,8 +3,6 @@
   xsi:noNamespaceSchemaLocation="http://www.adobe.com/xml/schemas/PolicyFile.xsd">
 <site-control permitted-cross-domain-policies="all"/>
 <allow-http-request-headers-from domain="*" headers="*"/>
-<allow-access-from domain="*.tokbox.com" to-ports="*"/>
-<allow-access-from domain="tokbox.com" to-ports="*"/>
-<allow-access-from domain="*.etherpad.com" to-ports="*"/>
-<allow-access-from domain="etherpad.com" to-ports="*"/>
+<allow-access-from domain="*.YOURDOMAIN_CHANGEME.com" to-ports="*"/>
+<allow-access-from domain="YOURDOMAIN_CHANGEME.com" to-ports="*"/>
 </cross-domain-policy>

./src/etherpad/pro/pro_utils.js

--- ./src/etherpad/pro/pro_utils.js.orig        2009-12-23 14:28:23.000000000 -0200
+++ ./src/etherpad/pro/pro_utils.js     2009-12-23 14:29:16.000000000 -0200
@@ -145,7 +145,7 @@
 }

 function getEmailFromAddr() {
-  var fromDomain = 'etherpad.com';
+  var fromDomain = 'YOURDOMAIN_CHANGEME.com';
   if (pne_utils.isPNE()) {
     fromDomain = getFullProDomain();
   }

./src/etherpad/globals.js

--- ./src/etherpad/globals.js.orig      2009-12-23 14:27:30.000000000 -0200
+++ ./src/etherpad/globals.js   2009-12-23 16:17:34.000000000 -0200
@@ -27,12 +27,11 @@
 }

 var SUPERDOMAINS = {
-  'localbox.info': true,
   'localhost': true,
-  'etherpad.com': true
+  'YOURDOMAIN_CHANGEME.com': true
 };

./src/etherpad/control/pro/pro_main_control.js

--- ./src/etherpad/control/pro/pro_main_control.js.orig 2009-12-23 14:37:44.000000000 -0200
+++ ./src/etherpad/control/pro/pro_main_control.js      2009-12-23 14:38:09.000000000 -0200
@@ -70,7 +70,7 @@

   renderFramed('pro/pro_home.ejs', {
     isEvaluation: licensing.isEvaluation(),
-    evalExpDate: licensing.getLicense().expiresDate,
+//    evalExpDate: licensing.getLicense().expiresDate,
     account: getSessionProAccount(),
     isPNE: pne_utils.isPNE(),
     pneVersion: pne_utils.getVersionString(),

./src/etherpad/control/pad/pad_control.js

--- ./src/etherpad/control/pad/pad_control.js.orig      2009-12-23 14:34:11.000000000 -0200
+++ ./src/etherpad/control/pad/pad_control.js   2009-12-23 14:34:37.000000000 -0200
@@ -661,7 +661,7 @@
              {toEmails: toEmails, padId: padId, username: username,
               subject: subject, message: message});

-  var fromAddr = '"EtherPad" <noreply@etherpad.com>';
+  var fromAddr = '"EtherPad" <noreply@YOURDOMAIN_CHANGEME.com>';
   // client enforces non-empty subject and message
   var subj = '[EtherPad] '+subject;
   var body = renderTemplateAsString('email/padinvite.ejs',

./src/etherpad/control/global_pro_account_control.js

--- ./src/etherpad/control/global_pro_account_control.js.orig   2009-12-23 14:35:13.000000000 -0200
+++ ./src/etherpad/control/global_pro_account_control.js        2009-12-23 14:35:28.000000000 -0200
@@ -125,7 +125,7 @@
     response.redirect(_recoverLink(accountList[0], domainList[0]));
   }
   if (accountList.length > 1) {
-    var fromAddr = '"EtherPad Support" <support@etherpad.com>';
+    var fromAddr = '"EtherPad Support" <support@YOURDOMAIN_CHANGEME.com>';
     var subj = "EtherPad: account information";
     var body = renderTemplateAsString(
       'pro/account/global-multi-domain-recover-email.ejs', {

Your Ether­Pad instance should be ready to go live and kick ass now!

RUN!

First, set the fol­low­ing envi­ron­ment variables:

# export JAVA_HOME="/usr/java/jdk1.6.0_17/"
# export JAVA="/usr/java/jdk1.6.0_17/bin/java"
# export SCALA="/home/etherpad/scala-2.7.7.final/bin/scala"
# export SCALA_HOME="/home/etherpad/scala-2.7.7.final/"
# export PATH=/home/etherpad/scala-2.7.7.final/bin/:$PATH
# export MYSQL_CONNECTOR_JAR="/usr/share/java/mysql-connector-java-5.0.8.jar"
# export mysql=mysql

then cre­ate the database,

# bin/setup-mysql-db.sh

com­pile it,

# bin/rebuildjar.sh

which out­puts:

using JAR fastjar...
lib/mysql-connector-java-5.0.8.jar has changed, rebuilding JAR
unzipping JARs...
making cached JAR....
compiling...
compiling with 'fsc'...
using cached common...
using cached sars...
using cached cli...
using cached bodylock...
using cached appserver...
using cached ajstdlib...
using cached etherpad...
using cached ooservice...
copying files...
obfuscating...
building javascript classfiles...
done.
copying cached JAR...
making JAR...
cleaning up...
done.
including etherpad JARs...
using cached JAR-etherpad...
updating...
done.
wrote /home/etherpad/trunk/etherpad/appjet-eth-dev.jar
which: no growlnotify in (/home/etherpad/trunk/etherpad/scala/bin/:/usr/kerberos/sbin:/usr/kerberos/bin:/usr/bin:/bin)

… and launch it!

# bin/run-local.sh 

Which out­puts:

Using config file: ./data/etherpad.local.properties
Using mysql database type.
Establishing mysql connection (this may take a minute)...
mysql connection established.
Checking for database migrations...
HTTP server listening on http://0.0.0.0:9000/
HTTPS server listening on https://0.0.0.0:9001/

Et Voilà! Your Ether­Pad instance is running!

Sight­see­ings

You can hit http://youdomain.com:9000/ now!

Start page

Cre­ate a new pad

Start page

Hit http://youdomain.com:9000/ep/admin, and use the ADMINPASS_CHANGEME to log in.

Get­ting a pro account

Hit http://yourdomain.com:9000/ep/pro-signup/

Pro account sign in

http://subdomain.yourdomain.com:9000/

Pro account admin interface

http://subdomain.yourdomain.com:9000/ep/admin

After­thoughts

Besides the first-hand expe­ri­ence, much of what was sum­ma­rized here came from the mem­bers of the Ether­Pad Open Source Dis­cus­sion google group. It’s very cool to watch and par­tic­i­pate of an active and gen­tle com­mu­nity com­ing into exis­tence almost overnight!

I believe Ether­pad will receive some love and pol­ish­ing soon by its main­tain­ers, and we’ll see it nicely pack­aged, with switches and knobs inside prop­erly placed con­fig files instead of these tweaks and scat­tered changes on hard­coded stuff all over the place!

A BIG THANKS to the AppJet/EtherPad team for this great prod­uct that is Ether­Pad, and to Google Inc. for “get­ting” opensource!

See also

If you came this far, you might also be inter­ested in:

• http://etherpad.com/ep/pne-manual/configuration-guide
• http://etherpad.com/ep/pne-manual/installation-guide
• http://code.google.com/p/etherpad/wiki/Instructions
• http://code.google.com/p/etherpad/wiki/FAQ
• https://wiki.ubuntu.com/Etherpad
• http://www.mclear.co.uk/2009/12/configure-etherpad-pro-after.html

I hope you enjoyed this guide. Feed­back and con­struc­tive crit­i­cism are highly appre­ci­ated! Thank you!

Nuba Prin­ci­galli