Setting-up Etherpad in a server subdirectory -aka- Apache config hell

🔗

Animation showing a difficult as hell platformer video game

I truly think Etherpad is an amazing piece of software. Not so much for its code base quality than for its extraordinary range of usages.

Now, while I'm still unsure if todo-lists are useful or a complete waste of energy, I'm convinced that keeping a developer logbook / diary / journal has many benefits (even The Pragmatic Programmer and Redis creator recommend it).

Then, don't get me wrong: paper notebooks are GREAT. I love them, and always carry one with me. But for the sake of durability, safety and hypertextuality, I often end up transfering most of my hand-written notes on my computer. And Etherpad is just the perfect tool for this. Why ?

  • its interface is slick, easy to grasp quickly, almost simplistic at first but with a bit of progressive disclosure
  • it provides the flexibility to add, remove or rearrange ideas way more easily than on paper
  • it allows quick copy & paste of URLs, code snippets, quotes, input text for a temporary backup copy... like some kind of cross-applications scratchpad/buffer
  • it has various font sizes, styles and colors : it is well-known in mind-mapping that this will help make your notes more stimulating, engaging & easy to remember
  • it allows simultaneous multi-users access
  • it has plenty of plugins : images preview, list of pads, syntax highlighting...
  • and above all: it provides a persistent history of changes

Hence my will to install a local instance on my server.

It all started off on the right foot: installing Etherpad on my Ubuntu laptop revealed to be easy as a pie.

But things became nasty when I had to serve it through Apache. The wiki guidelines did not work for me.

After hours of googling (more precisely duckduckgoing) and a stupid attempt to add an additional helpful entry to the Etherpad config (I was about to send a pull request on github when I realized how useless it was), I found the wisdom of the ancients on good old StackOverflow.

First, assuming you have an Etherpad node.js process ready & listening on port 9001, you'll have to configure Apache to use mod_proxy_html:

sudo apt-get install libapache2-mod-proxy-html libxml2-dev
sudo a2enmod proxy_html xml2enc

Then, there is the magic config:

<Location /pad>
  ProxyPass http://localhost:9001 retry=0
  # retry=0 => avoid 503's when restarting etherpad-lite
  ProxyPassReverse http://localhost:9001
  SetOutputFilter proxy-html
  ProxyHTMLURLMap http://localhost:9001
</Location>
RewriteRule ^/pad$ /pad/ [R]

Now simply restart Apache, and Bob's your uncle !

sudo service apache2 restart
sudo tail -F /var/log/apache2/*.log # watch that everything is OK

Animation showing a Powerrangers character stunt








Still here ? Ok, there is a last tip, in case you use either ep_small_list or ep_syntaxhighlighting plugins, to convert their bogus absolute URLs into relative ones:

grep -FIlR '"/static/' path/to/etherpad-lite/node_modules/ep_{small_list,syntaxhighlighting} | xargs sed -i 's~"/static/~"../static/~'
• • • • • • • • • • • • •