Introduction

Etherpad is a real-time, multi-user collaboration tool mainly for program development and web design. In this tutorial, we will focus on getting Etherpad running on a CentOS 6.4 VPS (cloud server). This guide will consider that you already have a set up, if you do not, simply follow this guide here.

Step 1 - Install the Required Libraries

Before we can install Etherpad, we need to install the required libraries and prerequisites for doing so.

Go ahead and execute the following command either as root or by adding sudo to the start of every command.

yum install gzip git-core curl python openssl-devel make gcc gcc-c++ postgresql-devel && yum -y groupinstall "Development Tools"

After that is complete, you will need to install the Node.JS library and the NPM library. So perform the following commands:

cd /tmp
wget http://mirror-fpt-telecom.fpt.net/fedora/epel/6/i386/epel-release-6-8.noarch.rpm
rpm -ivh epel-release-6-8.noarch.rpm
yum install nodejs npm

Congratulations, Node.JS and NPM are installed. Now we can get onto installing Etherpad!

Step 2 - Installing Etherpad

First, we will create a separate user for Etherpad. This will allow Etherpad to run independently from other users and is more secure than using root. This command will also create the user as well as a home directory.

useradd --create-home etherpad

Now, we will execute some commands so we can configure Etherpad as the newly created user.

su - etherpad
cd /home/etherpad

In order to get Etherpad going, we will need to download it first. Perform the following command to initiate the download from GitHub.

git clone git://github.com/ether/etherpad-lite.git

Step 3 - Install MySQL for Etherpad Database

While Etherpad uses it's own flatfile database for storage, this is not recommended for production use. Because of this, we will be installing MySQL and configuring Etherpad to use as a database.

We will assume you do not have MySQL installed currently, so run the following commands either as root or using sudo:

yum install mysql-server
service mysqld start
chkconfig mysqld on

After it has installed, run these commands. Be sure to replace PASSWORD with a secure password of your choosing:

mysql -u root -p
create database `etherpad-lite`;
grant all privileges on `etherpad-lite`.* to 'etherpad'@'localhost' identified by 'PASSWORD';
exit

Now, we will need to go into the Etherpad directory, so execute the following:

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

Open up the settings.json file with your favorite editor.

Find the following text:

"sessionKey" : "",

Change it to:

"sessionKey" : "SECURESTRING",

To state the obvious, replace SECURESTRING with a 10-18 alpha-numerical string.

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"
  //            	 },

Then find:

/* An Example of MySQL Configuration   "dbType" : "mysql",   "dbSettings" : {                    "user"    : "root",                    "host"    : "localhost",                    "password": "",                    "database": "store"                  },  */

Change it to the following (Taking care to ensure you remove the */ at the end):

// Etherpad MySQL Config   "dbType" : "mysql",   "dbSettings" : {                    "user"    : "etherpad",                    "host"    : "localhost",					 "port"    : "/var/lib/mysql/mysql.sock",                    "password": "YOURDBPASSWORD",                    "database": "etherpad-lite"                  },

Be sure to replace YOURDBPASSWORD with the password you set when creating the database. Save the file and close the editor afterwards.

Now we will need to let Etherpad install some dependencies for itself. So perform the following commands:

./bin/installDeps.sh

Once that has run through, we will need to run Etherpad for the first time so it can create the appropriate tables in the database. Run the following command:

./bin/run.sh

After Etherpad has loaded successfully, use Ctrl+C to kill the process. We will need to modify the Etherpad database for use before running it for real:

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

Step 4 - Running Etherpad

We have installed Etherpad successfully and configured it to use MySQL. From this point, in order to run it properly, execute:

./bin/run.sh

This script will initialize Etherpad and then start the process.

Keep in mind that Etherpad will terminate when you cancel/close your SSH session window. You can use the optional step to place Etherpad into a screen session for easier manageability.

Step 5 - Accessing Etherpad

Once you run the above script, you can access your Etherpad installation by browsing to: http://yourdomain.com:9001

You should be presented with an Etherpad page, asking you to create a pad or open an existing one.

Step 6 - Running Etherpad in Screen (Optional)

Utilizing screen can save you valuable time in case your client terminates unexpectedly. It allows you to keep your session active and return to it at anytime, even when you are logged out or your SSH client quits unexpectedly.

To install the screen program, simply perform the following command as root (su) or as a super user (sudo)

yum install screen

After it has installed, simply perform the following commands to run Etherpad within screen.

su - etherpad
cd /home/etherpad 
screen -dmS etherpad ./etherpad-lite/bin/run.sh

Etherpad should run immediately in the background.

In order to view your screen session, you will need to logout and login using your Etherpad user, but we must create a password for it first. Run the following command as root to create a password for the Etherpad user:

passwd etherpad

When this is completed, you can logout from your current SSH session and login as your Etherpad user.

Once logged in as your Etherpad user, run the following command to reattach to your screen session:

screen -r etherpad

To detach from screen and return to the bash prompt, simply press CtrlA+D at the same time. That is Control-A followed by a D.

NOTE: If the VPS loses power or is restarted, the screen session will be lost. You will need to run the commands again or utilize a startup script, such as the one found here.

Step 7 - Additional Configuration

This guide just shows the basics in getting Etherpad setup. There are other things you can do to improve your Etherpad installation that are not covered here.

For more information on further configuring Etherpad, please visit the Etherpad Wiki at: https://github.com/ether/etherpad-lite/wiki.