Etherpad – A Real Time Web Based Online Collaborative Document Editor for Linux

Etherpad is a web based free document editor tool which allows a group of users to work jointly on a document in a real time, like a multi player editor which runs on a web browser. Etherpad authors can edit and at the same time see each others edits in real time with a capability to display author’s text in their own colours.

This tool has a separate chat box in the sidebar allowing authors to communicate during editing. Etherpad is written in JavaScript both on server side and client side, so that it comes easy for developers to maintain and add new features.

Etherpad is designed in such a way that you can have access to all data through a well-documented HTTP API. This software also helps you to import/export data to many exchange formats and comes with translations too where authors can deliver correct language for their local settings.

For your reference, I’ve attached a Demo of Etherpad Lite at below link.

1. Watch EtherPad Demo

In this tutorial, I will describe how to install and configure Etherpad Lite a web-based real time collaborative document editing application on RHEL, CentOS, Fedora, Debian, Ubuntu and Linux Mint.

Installing Etherpad Lite on Linux

First, we need to download and install few required libraries and development tools. Open the terminal and run the following command either as root or by adding sudo at the beginning of each command.

Step 1: Install Libraries and Development Packages

You’ll need gzip, git, curl, libssl python, develop libraries, python and gcc packages.

On RHEL / CentOS / Fedora

# yum install gzip git-core curl python openssl-devel && yum groupinstall "Development Tools" For FreeBSD: portinstall node, npm, git

On Debian / Ubuntu / Linux Mint

$ sudo apt-get install gzip git-core curl python libssl-dev pkg-config build-essential

Step 2: Install Node.js

Additionally, you will also need to download and compile latest stable Node.js version from source packages using following commands.

$ wget http://nodejs.org/dist/node-latest.tar.gz
$ tar xvfvz node-latest.tar.gz
$ cd node-v0.10.23     [Replace a version with your own]
$ ./configure
$ make
$ sudo make install

Once you have successfully installed, verify the Node.js version using the command as follows.

$ node --version

v0.10.23

Step 3: Download and Install Etherpad Lite

We will create a separate user called “etherpad” to run Etherpad application independently. So, first create a user with its home directory.

# useradd --create-home etherpad

Now switch to “etherpad” user and download the latest stable version of Etherpad Lite using GIT repository as shown.

# su - etherpad
$ cd /home/etherpad
$ git clone http://github.com/ether/etherpad-lite.git

Once you’ve downloaded source files, change into the newly created directory containing the cloned source code.

$ cd etherpad-lite/bin

Now, execute run.sh script.

$ ./run.sh

Sample Output

Copy the settings template to settings.json...
Ensure that all dependencies are up to date...  If this is the first time you have run Etherpad please be patient.
[2013-12-17 05:52:23.604] [WARN] console - DirtyDB is used. This is fine for testing but not recommended for production.
[2013-12-17 05:52:24.256] [INFO] console - Installed plugins: ep_etherpad-lite
[2013-12-17 05:52:24.279] [INFO] console - Your Etherpad git version is 7d47d91
[2013-12-17 05:52:24.280] [INFO] console - Report bugs at https://github.com/ether/etherpad-lite/issues
[2013-12-17 05:52:24.325] [INFO] console -    info  - 'socket.io started'
[2013-12-17 05:52:24.396] [INFO] console - You can access your Etherpad instance at http://0.0.0.0:9001/
[2013-12-17 05:52:24.397] [WARN] console - Admin username and password not set in settings.json.  To access admin please uncomment and edit 'users' in settings.json

Step 4: Access and Create New Pad in Etherpad Lite

Now you should able to browse the web interface of Etherpad Lite at http://localhost:9001 or http://your-ip-address:9001 in a web browser.

Create a new document by giving a Pad name. Please remember, enter new name when creating a new document or enter name of the previously edited document to access.

For example, I’ve created a new document called “tecmint”. User’s can create multiple new pads in separate windows, each user’s document window appears on another window automatically in real-time. Each user’s window is highlighted in two different colours and also user’s can interact with each other using built-in chat box.

Each newly created document has its own URL structure. For example, my new “tecmint” pad get’s a URL as http://your-ip-address:9001/p/tecmint. You can share this document URL with your friends and colleagues. You can even embed the editor window into another HTML web page as an iframe.

You can save the document while editing is in progress by clicking the STAR button, however they are created periodically. To access a saved revision of the document add the number of the saved revision. For example, if you would like to see the saved revision number (i.e. 2) in this case, replace the number 6 with 2 at the http://your-ip-address:9001/p/tecmint/6/export/text.

Etherpad also comes with built-in feature called import and export, where you can import any external document or export a current saved document to a separate file. The document can be downloaded in HTML, Open Document, Microsoft Word, PDF or Plain text format.

A “time slider” feature enables anyone to explore the history of the pad.

Step 5: Using Etherpad Lite with MySQL Backend

By default Etherpad stores documents in a flat-file database. I suggest you to use MySQL as a backend to store created and edited documents. For this, you must have MySQL installed on your system. If you don’t have, install it on the system, you can install it using following commands as root user or using sudo.

On RHEL / CentOS / Fedora

# yum install mysql-server mysql
# service mysqld start
# chkconfig mysqld on

On Debian / Ubuntu / Linux Mint

# apt-get install mysql-server mysql-client
# service mysqld start

After MySQL has installed, connect to mysql shell by running a following command.

# mysql -u root -p

Once you in mysql shell, issue the following command to create the database.

create database etherpad_lite;

Grant permissions to a newly created database account. Replace “your-password” with your own password.

grant all privileges on etherpad_lite.* to 'etherpad'@'localhost' identified by 'your-password';

Leave the mysql client.

exit;

Now, switch to “etherpad” user and go into the etherpad directory and run the following commands:

# su - etherpad
$ cd /home/etherpad/etherpad-lite    
$ cp settings.json.template settings.json

Next, open settings.json with your choice of editor and change the settings as shown below.

# vi settings.json

Find the following text.

"sessionKey" : "",

Add the SECURESTRING with a minimum 10 alpha-numerical string.

"sessionKey" : "Aate1mn160",

Then find:

"dbType" : "dirty",
  //the database specific settings
  "dbSettings" : {
                   "filename" : "var/dirty.db"
                 },

And comment it out like so:

// "dbType" : "dirty", */
  //the database specific settings
  // "dbSettings" : {
  //                   "filename" : "var/dirty.db"
  //                 },

Next set mysql and admin settings as shown below.

  /* An Example of MySQL Configuration
   "dbType" : "mysql",
   "dbSettings" : {
                    "user"    : "etherpad",
                    "host"    : "localhost",
                    "password": "your-password",
                    "database": "etherpad_lite"
                  },

  */
  "users": {
    "admin": {
      "password": "your-password",
      "is_admin": true
    },

Make sure to replace “your-password” with the password you created above while setting up a new database account and an admin password with your own value. Now, we need to install some additional dependency packages with below command.

./bin/installDeps.sh

Once the script completes, we will need to run Etherpad script again. So, it can create the appropriate tables in the database.

./bin/run.sh

After Etherpad has loaded successfully, hit Ctrl+C to kill the process. Again login into mysql shell and alter the database to use correctly.

mysql -u root -p
alter database etherpad_lite character set utf8 collate utf8_bin;
use etherpad_lite;
alter table store convert to character set utf8 collate utf8_bin;
exit;

Finally, we’ve successfully installed and configured Etherpad to use MySQL backend. Now run the etherpad again to use MySQL as backend.

./bin/run.sh

The script will initialize Etherpad and then start the process. Please keep in mind that Etherpad application will terminate it’s process when you close your terminal session window. Optionally, you can use the screen command to place Etherpad into a screen session for easy access.

That’s it for now, there are lots more other things to explore and improve your Etherpad installation, which are not covered here. For example, you can use Etherpad as service in a Linux system or provide secure access to your user’s over HTTPS/SSL connection. For more information on further configuration visit the official page at:

1. Etherpad Lite Wiki