Etherpad is a lovely app which is bought by google and was opensourced 10 days before. Now, just to add a drop of water to the ocean.
A small how-to on deploying Etherpad
The package
- Etherpad source from http://code.google.com/p/etherpad
- Some minor fixes and changes, here and there
- File Imports [gist]
- File exports to DOC/PDF/ODT using Oo.org [gist]
How to compile, run and test
- Grab the code from my github repository
$ git clone git://github.com/karteek/etherpad.git
You can optionally do a diff -r to above created clone with original clone to see the changes I’ve made to the code. -
Set up the environment to compile the code. Open the provided env.sh, and look at the needed variables. Existing values are values from my MBP, and they most probably won’t work for you
$ source env.sh -
Create a database “etherpad” on your MySQL database. Same time, create a user “etherpad” with password “password” and grant him all privileges on the database “etherpad”
-
Update etherpad.SQL_JDBC_URL, etherpad.SQL_USERNAME, etherpad.SQL_PASSWORD and etherpad.adminPass in the file etherpad/etc/etherpad.localdev-default.properties
- etherpad.SQL_JDBC_URL is the jdbc URL of your database (in our case, its jdbc:mysql://localhost:3306/etherpad )
- etherpad.SQL_USERNAME is the username to connect to database (in our case, its etherpad)
- etherpad.SQL_PASSWORD is the password to connect to database (in our case, its password)
- etherpad.adminPass is the password needed to login to admin panel of Etherpad instance
- Change directory to etherpad, compile the jar, and start the server
$ cd etherpad
$ bin/rebuildjar.sh
$ bin/run-local.sh - Now, fire up your browser, and visit http://localhost:9000 to play with your instance
File Imports
- File Imports depend on com.oreilly.servlet (cos.jar found at http://www.servlets.com/cos/)
- Check their license @ http://www.servlets.com/cos/license.html. If you are fine with their license, download cos.jar and copy it to infrastructure/lib folder
- Search for locations where file upload related code is commented, and uncomment the code.
$ grep -r “REMOVED_COS_OF_COS” * - Recompile the package
$ cd etherpad
$ bin/rebuildjar.sh
File Exports
- File exports depend on Openoffice.org for conversion
- You need to start Oo.org as a service
$ /path/to/openoffice/soffice.bin -headless -nofirststartwizard -accept=”socket,host=localhost,port=8100;urp;StarOffice.Service” - Just make sure that etherpad.soffice has some value in etherpad/etc/etherpad.localdev-default.properties
- Check infrastructure/com.etherpad.openofficeservice/importexport.scala for more information
How to deploy the same on example.com
- Wild card dns for your domain. Point *.example.com to same server where example.com resides. This is the server where you are deploying this instance.
- Make sure that your SMTP is working. Activation of Pro accounts happen over email, so its important.
- Open etherpad/src/main.js, and update domain in line #273
- Open etherpad/src/etherpad/globals.js and change the domain in variable SUPERDOMAINS found at line #30
- Open etherpad/src/static/crossdomain.xml and add your domain to crossdomains.xml
- Look into etherpad/src folder and search for etherpad.com. You will find many locations, where your instance will be coded to mail from an @etherpad.com account. Update all of them to your domain.
$ grep -ir “etherpad.com” * - Open etherpad/etc/etherpad.localdev-default.properties and update
- devMode to false
- etherpad.isProduction to true
- listen to example.com:80
- etherpad.isPNE to true (only if you want to run in PNE mode)
- And ofcourse, change etherpad.adminPass
- As long as you din’t change anything in infrastructure folder, you need not recompile the jar. So, just go ahead and start the server. For starting a server on port numbers less than 1000, you will need to have root access on OS X.
Running the instance behind Apache using mod_proxy
- Do the same as above from steps #1 to #7.
- In step #7, rather than changing listen to example.com:80, change it to localhost:9000 or just 9000
- Start the server using bin/run-local.sh
- Your apache configuration might look like -
<VirtualHost *:80>
ServerName www.example.com
ServerAlias *.example.com
ServerAdmin admin@example.com
ErrorLog /var/log/apache2/etherpad.error.log
LogLevel warn
CustomLog /var/log/apache2/etherpad.access.log combined
ServerSignature Off
ProxyPass / http://localhost:9000/
ProxyPassReverse / http://localhost:9000/
ProxyPreserveHost on
<Proxy *>
Options FollowSymLinks MultiViews
AllowOverride All
Order allow,deny
Allow from all
</Proxy>
</VirtualHost> - This might or might not work for you. Anyway, I guess you got the idea. Check manual for more information
Well, the patch I wrote for enabling file exports so as this tutorial come with no warranty. Don’t ask me even if it breaks your bones. This is what I did, following it is completely your choice. Code from Etherpad is under the license they specified. The file import part depends on MultipartWrapper and MultipartFilter. If you don’t like their license, its better to write your own code for doing their work.
Feel free to ask any doubts and/or fix my bugs. There is a great tutorial on installing Etherpad by Nuba Princigalli. Do check it, if you find any problems with my post.
