Etherpad Lite up ’n’ running in 5 minutes

Etherpad Lite is a lightweight version of (probably) the most popular web-based collaborative real-time editor - Etherpad. This great peace of software allows multiple users to edit the same document in real-time. To make collaboration easier, users have built-in chat at their disposal. History playback, infinite undo, easy import and export of documents are some of the cool stuff it has to offer. Compared to the original, EL has very short system requirements list, which makes it very easy to deploy. Since it’s written in server-side JavaScript using Node.js, to make it functional for testing/development purposes you’ll need only Node.js, but for everyday/production usage it’s recommended that you use a web server (e.g. Apache or Nginx) and MySQL.

Prerequisites

First you’ll need to install dependencies. If you’re using Red Hat based distro (like CentOS or Fedora) you can use yum:

# yum install gzip git-core curl python openssl-devel make gcc gcc-c++

If you’re using Debian based distro (like Ubuntu), you can use apt-get:

# apt-get install gzip git-core curl python libssl-dev build-essential

Installation

Download the latest stable version of Node.js, unpack it and compile it:

# tar xf node-v0.6*
# cd node-v0.6*
# ./configure && make && make install

Now you can download the latest version of EL and install its dependencies:

# cd /home/etherpad/ && git clone 'git://github.com/ether/etherpad-lite.git'
# ./etherpad-lite/bin/installDeps.sh

At this point you have basic setup for testing EL. To run it, simply execute the startup script (preferably as etherpad user and not as root):

$ ./etherpad-lite/bin/run.sh

By default, EL binds itself to port 9001, so you can use it by opening http://localhost:9001

Configuration

I’ll assume that you have Nginx and MySQL installed, so I’m not going to explain how to install and configure them. Instead, I’m going to jump right onto the configuration of EL.

MySQL

Connect to MySQL server and create a database for EL.

# mysql -u root -p
mysql> create database etherpad;
mysql> grant all privileges on etherpad.* to 'etherpad'@'localhost' identified by 'SomePassword';
mysql> exit

Now you can set up the connection string in EL’s configuration file - settings.json. There are couple of variables you’ll need to change/set. Default values for ip and port are alright, however you’ll have to change dbType from dirty to mysql and, of course, change dbSettings. If you want to restrict access to EL you can uncomment httpAuth variable and enter username and password. Example of settings.json file:

/*
  This file must be valid JSON. But comments are allowed
  Please edit settings.json, not settings.json.template
*/
{
  //Ip and port which etherpad should bind at
  "ip": "127.0.0.1",
  "port" : 9001,
  /* An Example of MySQL Configuration*/
   "dbType" : "mysql",
   "dbSettings" : {
                    "user"    : "etherpad",
                    "host"    : "localhost",
                    "password": "SomePassword",
                    "database": "etherpad"
                  },
  //the default text of a pad
  "defaultPadText" : "Welcome to Etherpad Lite!\n\nThis pad text is synchronized as you type, so that everyone viewing this page sees the same text. This allows you to collaborate seamlessly on documents!\n\nEtherpad Lite on Github: http:\/\/j.mp/ep-lite\n",
   
  /* Users must have a session to access pads. This effectively allows only group pads to be accessed. */
  "requireSession" : false,
  /* Users may edit pads but not create new ones. Pad creation is only via the API. This applies both to group pads and regular pads. */
  "editOnly" : false,
  /* if true, all css & js will be minified before sending to the client. This will improve the loading performance massivly,
     but makes it impossible to debug the javascript/css */
  "minify" : true,
  /* This is the path to the Abiword executable. Setting it to null, disables abiword.
     Abiword is needed to enable the import/export of pads*/
  "abiword" : null,
  /* This setting is used if you need http basic auth */
  //"httpAuth" : "user:pass",
  /* The log level we are using, can be: DEBUG, INFO, WARN, ERROR */
  "loglevel": "INFO"
}

After editing the configuration file, it’s time to start EL in order to check if everything is in order. Just like before, you just need to execute run.sh script. If you configured everything correctly, EL will start successfully and create single database table named store.

Just to make sure, you should set utf8 character set and collation to both database and its table:

# mysql -u root -p
mysql> use etherpad;
mysql> ALTER DATABASE `etherpad` CHARACTER SET utf8 COLLATE utf8_bin;
mysql> ALTER TABLE `store` CONVERT TO CHARACTER SET utf8 COLLATE utf8_bin;
mysql> exit

Nginx

To put EL behind reverse proxy (in this case Nginx), you will need an virtualhost that looks something like this:

server {
    listen       80;
    server_name  your.domain.tld;
    access_log   /var/log/nginx/your.domain.tld.log;
    error_log    /var/log/nginx/your.domain.tld.log;
    location / {
        proxy_pass        http://localhost:9001/;
        proxy_set_header  Host $host;
        proxy_buffering   off;
    }
}

Init script

To make your life easier, you should configure EL to run as a service. If you’re running Red Hat based distro, just copy the init script shown below to /etc/init.d/etherpad, just make sure that you have defined correct paths for variables path, prog, log, conf and lockfile:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

#!/bin/sh
#
# etherpad-lite - this script starts and stops the etherpad light daemon
#
# chkconfig: - 64 36
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 2 3 4 6
# Required-Start:
# description: etherpad lite is a collaboration editor
# processname: node
# config: /srv/etherpad-lite/settings.json
# pidfile: none
# lockfile: /var/lock/subsys/etherpad-light
# Source function library.
. /etc/rc.d/init.d/functions
# Source networking configuration.
. /etc/sysconfig/network
# Check that networking is up.
[ "$NETWORKING" = "no" ] && exit 0
progname="Etherpad Lite"
path="/home/etherpad/etherpad-lite/node"
prog="/usr/local/bin/node"
parameter="server.js"
log="/home/etherpad/etherpad-lite/log/error.log"
conf="/home/etherpad/etherpad-lite/settings.json"
user="etherpad"
lockfile="/var/lock/subsys/etherpad-light"
logpath=$(dirname $log)
start() {
        [ -x $prog ] || exit 5
        [ -f $conf ] || exit 6
        [ -d $logpath ] || mkdir $logpath
        [ -f $log ] || touch $log
        chown $user $logpath
        chown $user $log
        echo -n $"Starting $progname: "
        daemon --user=$user "cd $path; $prog $parameter >>$log &"
        retval=$?
        echo
        [ $retval -eq 0 ] && touch $lockfile
        return $retval
}
stop() {
        echo -n $"Stopping $progname: "
        killproc $prog
        retval=$?
        echo
        [ $retval -eq 0 ] && rm -f $lockfile
        return $retval
}
restart() {
        stop
        start
}
rh_status() {
        status $prog
}
rh_status_q() {
        rh_status >/dev/null 2>&1
}
case "$1" in
        start)
                rh_status_q && exit 0
                $1
        ;;
        stop)
                rh_status_q || exit 0
                $1
        ;;
        restart)
                $1
        ;;
        status)
                rh_status
        ;;
        *)
                echo $"Usage: $0 {start|stop|status|restart}"
                exit 2
esac

When you’re done, make the init script executable and start etherpad:

# chmod 755 /etc/init.d/etherpad
# service etherpad start

Init scripts for other distributions can be found here.

Upgrading

Upgrading EL is super easy and it’s done by pulling the changes from git repository:

$ cd /home/etherpad/etherpad-lite/
$ git pull origin

You don’t have to worry about settings.json configuration file. It won’t be overwritten 😉