by

Collaborative Writing with Etherpad-Lite on Mac OS X

We are huge fans of collaborative writing here at ProfHacker. I think there is still huge potential for growth in this area. When I sit next to a friend in a conference audience who has never collaboratively written anything in Google Docs and suggest we take notes together, or the same with a group of friends who are assembling ideas for a project, I have yet to be disappointed by the speed with which the advantages to the approach are understood and the practice adopted.

Though we have talked about a number of alternatives here, I still find GDocs to be the best. However, my continued dependence on Google Docs makes me uneasy. I would love for an easy to use, cross-platform, open source alternative to get widely adopted. The leading candidate is currently Etherpad lite. Both Etherpad and a number of similar kinds of collaborative editing environments have online homes you can go to create a document and begin working together. But what if you want to “roll your own” and host and keep your own documents without dependence on an online service beyond your control? Etherpad lite gives you that option. It is not quite there yet in terms of making this easy for users in the way that commercial client software such as SubEthaEdit does. As will become clear below, at least one person in a group of collaborators needs to be comfortable with the technical requirements to set up an Etherpad server that can “host” the repository of pads either on their own machine or a server they control.

For those of you who want to try it out on your own Mac OS X computer, read on. I base much of what I wrote below (with some expansion and changes) on a helpful blog entry on the topic by Oliver Heller (Twitter: @d24m) found here.

Open up your terminal and let us get down to it:

Etherpad uses a javascript web server environment called node.js. Many hosting companies do not support node.js yet so if you want to run Etherpad through a hosting service you need to make sure to choose a web host that does. To run it on your own computer, you will need to install node.js, its “package manager” npm, edit the settings, and “run” the Etherpad server.

  1. Install homebrew, which is useful for installing a lot of command line software.
  2. Use homebrew to install node.js with
    brew install node
  3. When it is done, install npm with this command:
    curl https://npmjs.org/install.sh | sudo sh
    Note: I got a message that suggests homebrew may have already installed npm without this step
  4. Create a folder (mkdir <foldername>) somewhere for your etherpad installation. Move into that folder (cd <foldername>)
  5. Download etherpad from its open source repository on github:
    git clone https://github.com/ether/etherpad-lite
  6. Modify a file called settings.json inside the new etherpad-lite folder created (see below) to indicate the database where you will save all the pads/documents. This can be done, for example, with a command like
    nano etherpad-lite/settings.json
    (though I prefer vi to nano).
  7. You can launch your Etherpad server with
    etherpad-lite/bin/run.sh
    Note: the server will run directly in this session of the terminal and if you close the window the server will shut down. You can use various approaches not covered here to run it in the background and have it start up when you launch your computer, etc.
  8. You should now be able to open Etherpad in your browser. On your own computer, open
    http://localhost:9001
    Note: People on your local network — if you give them your IP address and the port 9001 (example: 10.0.1.15:9001) — should also be able to open Etherpad, and your collaborative work can begin. However, if you have a static IP, it is a more complicated task to get your installation of Etherpad viewable to those beyond your local network, and working with a web hosting company that supports node.js makes more sense.

In step 6 above, you will see that you need to modify a settings file which indicates a database for the files to be saved. If you don’t create/edit the settings.json file all your pads will be saved in a “dirty.db” file. This is not recommended by the developers. Instead, you should probably install or configure a database in MySQL (installed via XAMPP or an alternative) that Etherpad can connect to (various places online on how to do this, including here).

As can be seen from the above, this is not fun for anyone who has limited experience with installing things on the command line. The end result, however, is a home for collaborative writing under your control, without dependence on Google or another organization. As with all tasks that involve running services (MySQL server, Node.js, etc.) on your home network, these become possible openings for attack from the outside. If you only going to be using it on your local network, then consider learning how to configure your service or your firewall to only accept connections from the local network, or a small set of machines. If you install a package such as then look into how to “hardened” it.

Does you have other suggestions for open source collaborative writing tools that might work across platforms? What has your experience been with Etherpad or similar tools? Please share in the comments.

Image from the Etherpad.org Creative Commons licensed homepage.

Return to Top