Annotate Server Installation Guide for Mac OSX servers.

This chapter includes instructions for installing your own version of the Annotate server on Mac OSX.

You will also need to refer to the main server installation guide as this guide just covers the Mac OSX specifics.


Before you install Annotate, you need to have:

  • The Mac Xcode developer tools, which includes utilities like a compiler and make tools.
  • Apple's X11 installed.
  • An Apache web server running PHP5. OSX includes a bundled version of Apache, but you may wish to install a more recent version using MacPorts (Formerly known as Darwin ports). Warning: the MAMP distribution is very easy to install, but has a shared library clash with the netpbm utilities so is not recommended for Annotate.
  • The Xpdf and Netpbm open source utilities. The Fink Project includes tools for installing these open source packages.

1. Installing Apache and PHP5 on Mac OSX

You can install Apache and PHP using MacPorts Install MacPorts - there are several help guides on the internet e.g. Guide to installing Apache / PHP using MacPorts. Note you do not need to install MySQL to run an Annotate server. Once you have installed MacPorts you can enter commands like the ones below to install apache / php. You will want to edit the settings in /opt/local/apache2/conf/httpd.conf, especially setting the DocumentRoot to an appropriate location.

sudo port install apache2
sudo port install php5 +apache2

# ... then edit /opt/local/apache2/httpd.conf to set DocumentRoot
# to the root folder, e.g. "/Users/joe/www/"

# If you don't have curl installed ('which curl') you should
# install it with:
sudo port install curl

As an alternative to using MacPorts - OSX Leopard comes with Apache and PHP5 installed but not enabled; Tiger has an older Apache bundled, so you might prefer to use the MacPorts version. See an online guide like Enabling Apache + PHP on Leopard (external). Apple's bundled version of Apache stores config settings in /Private/etc/apache2/httpd.conf and has a default DocumentRoot of /Library/WebServer/Documents

You can check whether you have the correct version of your web server / php installed by storing a PHP test file 'phpinfo.php' containing the call: <?php phpinfo(); ?> in your html document area and pointing your browser at it.

2. Installing XPDF and Netpbm on Mac OSX

Annotate requires the Xpdf set of utilities (version 3.02) and also Netpbm for converting image formats. The Fink project includes suitable packages configured for OSX - but you need to compile from source to get the up to date versions.

See the Fink download page to install the Fink package manager. Having installed Fink, you should update it to the latest version - sample commands:

fink selfupdate-rsync
fink update-all
fink scanpackages

# To complete the update you may be prompted to run:
sudo apt-get update
sudo apt-get install gettext=0.10.40-25

You also need to configure Fink to use the latest Source versions of packages, rather than the Binaries - this is because the binary versions tend to be out of date.

fink configure
# ... and get fink to install from Source to get the latest versions -

You can then install Xpdf and all its dependencies using: (note this may take an hour or so, as there are a number of font and X11 libraries needed).

fink install xpdf

To get the Netpbm utilties (ppmtopng etc), use the command below (again this may take a while as it will fetch and compile all the utilities).

fink install netpbm10 netpbm10-shlibs netpbm-bin

You can test that xpdf and netpbm have installed OK by typing:

xpdf -?
# This should say 'version 3.02' --- if it says version 3.00
# you'll need to update.

pnmtopng -version

3. Download and Install Annotate

Having installed the dependencies, you can download the standard version of the Annotate server and unpack into your Apache DocumentRoot area, e.g. "/Users/joe/www/annotate/". Assuming you have installed Xpdf and Netpbm utilities, you can jump to Step 3 of the installation guide.

For Step 4 you will need to copy and edit the Mac OSX version of the phpconfig file:

cd annotate/php
# edit the settings in to match your license code / paths

The sample file sets the paths of the xpdf and netpbm utilities to /sw/bin/ - assuming you installed them using the Fink package manager.

Questions / problems:

Please get in touch here.