This is how to install the etherpad from in a FreeBSD-8.2 jail. (N.B: Things are reported not to work with newer versions.)

This guide assumes, you have sudo, bash and an editor of your choice installed. Reserve around 2GB space for the jail. If you're using a different shell, use setenv to configure the environment variables set by export in this guide. Send feedback to erdgeist. Many regards to this guide, it helped me a lot.

Install Scala + Java

Since etherpad does not build under the version of scala that is shipped with FreeBSD-8.2 (i.e. scala-2.8.0), we have to manually install scala-2.7.7. However, scala brings nice dependencies that help with the manual installation of the jdk. So we install scala-2.8.0 to get the dependencies, then deinstall it and install java and scala.

Then type:

pkg_add -r scala
pkg_delete -f scala\*
pkg_add jdk- scala-2.7.7.tbz

Install mysql, fastjar and java connector


pkg_add -r mysql55-server mysql-connector-java fastjar
echo mysql_enable=YES >> /etc/rc.conf
/usr/local/etc/rc.d/mysql-server start

Prepare mysql

Connection in a jail comes from the jail IP, not from, so enter IPADDRESS accordingly

mysql -u root

and in the mysql shell:

create database etherpad;
grant all privileges on etherpad.* to 'etherpad'@'IPADDRESS' identified by 'MYSQLPASS_CHANGEME';

Checkout etherpad


pkg_add -r git
cd /usr/local
git clone git://

known good commit 94d5b2dfd65abbee5a06d80d94cdb00a7947d9b1, otoh: you might want to check my issue about this commit, overlay windows are broken atm.

Configure etherpad


cd /usr/local/pad/etherpad
cp etc/ etc/

and in your etc/ do:

  • Change: devMode = false
  • Change: etherpad.isProduction = true
  • Change: etherpad.proAccounts = true
  • Change: etherpad.adminPass = ADMINPASS_CHANGEME
  • Change: etherpad.isProduction = true
  • Change: listen =
  • Change: topdomains = pads.domain.tld,localhost
  • Change: customEmailAddress = admin@pads.domain.tld
  • Change: transportUseWildcardSubdomains = false
  • Change: useHttpsUrls = true

Remember the passwords well, take special care about trailing spaces! Now setup your domain in the following files:

  • src/main.js
  • src/static/crossdomain.xml
  • src/etherpad/pro/pro_utils.js
  • src/etherpad/control/pad/pad_control.js
  • src/etherpad/control/global_pro_account_control.js

To disable a per-pad quota, comment out the call to _checkPadQuota in src/etherpad/control/pad/pad_control.js

Rebuild the JAR


export JAVA_HOME="/usr/local/jdk1.6.0/"
export JAVA="/usr/local/jdk1.6.0/bin/java"
export SCALA="/usr/local/share/scala-2.7.7/bin/scala"
export SCALA_HOME="/usr/local/share/scala-2.7.7/"
export SCALA_LIBRARY_JAR="/usr/local/share/scala-2.7.7/lib/scala-library.jar"
export PATH=/usr/local/share/scala-2.7.7/bin/:$PATH
export MYSQL_CONNECTOR_JAR="/usr/local/share/java/classes/mysql-connector-java.jar"
export mysql=mysql

Rebuild the ace dependency

This is especially important if you see this (google hint): net.appjet.bodylock.JSRuntimeException: Error: Neither module exists: etherpad.collab.ace.easysync2, etherpad.collab.ace.easysync2.:

cd /usr/local/pad/infrastructure/ace
bin/make normal etherpad

Rebuild the JAR with correct settings


cd /usr/local/pad/etherpad

Install nginx


cd /usr/ports/www/nginx
make install clean

and be sure to select HTTPS.

Create Self Signed Certificates

For whatever your domain is, substitute it in the following commands:

openssl genrsa -out pads.domain.tld.key 1024
openssl req -new -key pads.domain.tld.key -out pads.domain.tld.csr
echo "subjectAltName=DNS:pads.domain.tld,DNS:*.pads.domain.tld" >pads.domain.tld.conf
openssl x509 -req -days 365 -in pads.domain.tld.csr -signkey pads.domain.tld.key -text -extfile pads.domain.tld.conf -out pads.domain.tld.crt
cat pads.domain.tld.crt pads.domain.tld.key >/usr/local/etc/nginx/pads.domain.tld.pem

Configure nginx

Nginx configs were provided by cryx. Thank you. Fetch nginx.conf here: nginx.conf and put it to /usr/local/etc/nginx/. Then in your local nginx.conf do:

  • Change: server_name pads.domain.tld *.pads.domain.tld; take special care to include the wildcard subdomains
  • Change: ssl_certificate pads.domain.tld.pem; as created above

Fetch nginx-etherpad.conf here: nginx-etherpad.conf and put it to /usr/local/etc/nginx/. Then in your local nginx-etherpad.conf do:

  • Change: server_name pads.domain.tld *.pads.domain.tld; take special care to include the wildcard subdomains
  • Change: proxy_pass http://pads.domain.tld:9000/;


mkdir /var/log/www/; chown www:www /var/log/www
echo nginx_enable=YES >> /etc/rc.conf

Install start script

Fetch rc script here: etherpad and put it to /usr/local/etc/rc.d/.


chmod +x /usr/local/etc/rc.d/etherpad
echo etherpad_enable=YES >> /etc/rc.conf
mkdir /var/run/etherpad; chown etherpad /var/run/etherpad
chown -R etherpad:etherpad /usr/local/pad

Install openoffice

If you want to export word and pdf documents, you need to install openoffice and run it as a headless service.

Fetch the libreoffice package here: or, a know working mirror for libreoffice-3.3.3.tbz, MD5 (libreoffice-3.3.3.tbz) = 028d259735b361e46af8a9e253f168a8.

Install dependencies, ignore warnings about already installed older versions:

pkg_add -r xineramaproto xf86vidmodeproto xextproto videoproto renderproto randrproto printproto kbproto inputproto fixesproto dri2proto damageproto compositeproto font-util encodings libtextcat expat gnome_subr ca_root_nss hicolor-icon-theme gnomehier lp_solve python27 xcb-proto perl hu-hunspell poppler-data png lcms jpeg jbigkit tiff openjpeg jasper curl pkg-config xproto pixman libtasn1 libfontenc libXdmcp libXau libICE libSM freetype2 mkfontscale mkfontdir fontconfig font-misc-meltho font-misc-ethiopic font-bh-ttf bitstream-vera xorg-fonts-truetype pcre orc m4 libpthread-stubs libxcb xcb-util libdrm libX11 libXt libXrender libXft libXfixes libXext libXxf86vm libXv libXrandr libXpm libXp libXmu libXinerama libXi libXdamage libXcursor libXcomposite libXaw libGL libGLU libltdl libffi libcheck icu db41 libiconv libxml2 raptor rasqal redland gettext libgpg-error libgcrypt glib gamin gio-fam-backend shared-mime-info libIDL gdk-pixbuf desktop-file-utils dbus libgee dbus-glib eggdbus cairo poppler bison gobject-introspection gstreamer gstreamer-plugins polkit pango ORBit2 lzo2 gnutls cups-client atk gtk dconf gconf2 libgsf libwpd libwps libwpg libxslt

Install the local package:

pkg_add -f libreoffice-3.3.3.tbz

Fetch rc script here: soffice and put it to /usr/local/etc/rc.d/. Then type:

chmod +x /usr/local/etc/rc.d/soffice
echo soffice_enable=YES >> /etc/rc.conf

Configure name server

Add records for the pads and wildcard subdomains, for tinydns this is:


Filter local services

Add rules to filter ports 9000 and 3306 to pf.