A.nnotate Server Installation Guide

This section explains how to install the A.nnotate server on your own hardware. It assumes you are familiar with command line access to a Linux web server.

An installation guide for A.nnotate for Windows servers (win32 / IIS or Apache) is now available too; see also A.nnotate for Mac OSX servers.

A.nnotate can also now be run on pure Java servlet containers using Quercus - see: A.nnotate for Java using Quercus.

This guide describes how to install version 3.1 of the A.nnotate server (v3.1.30 updated Mar 2015). If you are upgrading from a previous release, please check the upgrading notes at the end of this document before installing.

This chapter describes the steps needed to get a basic install of the A.nnotate server up and running on your server. This will work for annotating uploaded PDF documents and snapshots of HTML web pages. There are also a number of optional modules you can install once the basic system is up and running, for supporting Word and OpenOffice documents, displaying a progress bar during upload, and generating thumbnail images of snapshots: see Part 2: Installing A.nnotate modules for details once you have followed the steps below.

Contents

Prerequisites

The A.nnotate server requires a Linux server running Apache and PHP 5, to which you have SSH login access. This is provided by many web hosting companies as a 'virtual server' or a 'dedicated server'. (see also A.nnotate for Windows servers and A.nnotate for Mac OSX servers ).

  • A Linux server to which you have SSH access.
  • Apache
  • PHP 5 (with the JSON module enabled)
  • Java Runtime Environment (to enable exporting PDF with comments)
  • standard compile tools: make, g++

You can check whether you already have the correct version of apache / 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.

For example, starting with a vanilla Fedora Core 4 system with Apache and PHP 5 already installed: (the commands may be different if you use a different version of Linux): 

... e.g. to install PHP and Apache on Fedora Linux, as root:
  % yum install httpd 
  % yum install php 

To restart the apache server after changing the config:
  % service httpd restart

You should check/edit the following settings in your PHP configuration file which will be located somewhere like /etc/php.ini - the phpinfo() call will detail where it is on your system: 

; Some settings to check / edit in your php.ini file (e.g. /etc/php.ini):

; Check safe_mode is set to 'Off'
safe_mode = Off

; You might need to increase the limits below to allow uploading larger files
max_execution_time = 30    
max_input_time = 60    
memory_limit = 128M    
post_max_size = 8M

; Check this
file_uploads = On

; Maximum allowed size for uploaded files - may need increasing:
upload_max_filesize = 2M

; This needs to be 'On' : 
allow_url_fopen = On

Having made any changes, restart your web server and check the phpinfo() output. You need to make sure the safe_mode setting is Off to allow PHP to run the pdf conversions needed for A.nnotate to work. Recent versions of PHP5 include JSON as standard; if you use an older distribution (like CentOS) you may need to install it, e.g. see [installing PHP-JSON on CentOS].

Apache configuration settings

You need to configure your Apache server to enable .htaccess security controls, by checking your httpd.conf settings file. In the <Directory> section which points to the root of your web server, make sure that AllowOverride All is set (it may be set to "None" by default).

You may wish to enable optional modules in your httpd.conf file: mod_headers, mod_rewrite and mod_expires. You can do this by uncommenting the LoadModule entries which refer to these components and restarting your web server (or in Ubuntu copying expires.load and rewrite.load from /etc/apache2/mods-available to /etc/apache2/mods-enabled) These allow you to optimize the use of browser caches to reduce server load: see apache cache settings.

Step 1: Download and unpack the code

The A.nnotate code is written in PHP, with the user interface written in Javascript code.

You can get the code from the link below. A password is required to access the download; this will be supplied with your evaluation agreement or license contract. The download link contains all code necessary to run a local installation of the A.nnotate server including the integration API. This download is suitable for both Linux and Mac OSX:

Please note that the code is copyright Textensor Limited (apart from the xpdf code which is distributed under a GNU license). If you install it for production use, you must purchase a license.

We recommend you use the latest version above; however earlier versions are still available: v3.1.19 (jan 2011)

The steps below assume you are installing to the annotate/ subdirectory of your apache installation, and are installing the code as the user "annotate".

You can create this directory as root and use chown / chgrp to change the owner to the "annotate" user in the examples below. You can install annotate in any directory, but note that the installation directory should not contain any spaces (e.g. if you want separate words use a directory name like 'my-annotate' rather than 'my annotate').

The examples below assume we are installing into '/var/www/html/annotate'; depending on your apache installation this could be somewhere like: '/var/www/vhosts/yoursite.com/httpdocs' instead. 

# as root, create a new 'annotate' user and group for the install:
# e.g.:
  % groupadd annotate
  % useradd -g annotate annotate
  % mkdir /var/www/html/annotate          # or your preferred install location,
  % chown annotate /var/www/html/annotate
  % chgrp annotate /var/www/html/annotate 
  % su annotate

# as the 'annotate' user:
  $ cd /var/www/html/annotate            # or /var/www/vhosts/yoursite.com/httpdocs  etc.
    ### If you are reinstalling, make a safe copy of any edited files before unpacking ###
  # ... Copy the annotate-server-3.x.x.tgz file here...
  $ tar xvfz annotate-server-3.x.x.tgz
  $ make install                         # this creates the data directories

The server unpacks within the current directory. 

    index.php
    ...
    js/                                # the annotate javascript
    css/                               # CSS styles
    img/                               # images
    php/                               # the annotate server code
    scripts/                           # scripts for running openoffice (optional)
    cgi-bin/                           # cgi scripts for file upload progress (optional)
    docs/                              # public web-readable directory
    private/                           # private data directory

'make install' makes a .htaccess file in the private/ directory to prevent web access via Apache; you should check you have enabled .htaccess support in your Apache configuration. (see the Apache docs).

Step 2: Installing the necessary xpdf and image utilities

The packages a.nnotate depends on are: 

  xpdf-3.03  (for:  pdfinfo,  pdftoppm)
  netpbm, netpbm-progs, netpbm-devel     (for:  pnmquant, pamfile, ppmtogif)   
  pngquant (optional)
  libtiff-tools (optional, for: tiff2pdf)
  curl   
  ghostscript-fonts
  libstdc++

You should be able to use your standard package manager (e.g. yum, apt) on your linux distribution to install these, or they may already be available. You can type 'make check' (where you typed 'make install') to check that the utilities are installed. If they are not installed, you can use commands like the ones below to install: (Mac OSX users: see the A.nnotate for Mac OSX guide) 

  # as root...
  ... e.g. on Fedora Linux:
  % yum install netpbm netpbm-progs netpbm-devel xpdf curl ghostscript-fonts libstdc++ gcc-c++

  ... on Ubuntu the packages have different names:
  % sudo apt-get install netpbm libnetpbm10 libnetpbm10-dev xpdf curl pngquant libtiff-tools

Note that a.nnotate requires version 3.02 or later of the XPDF tools - some older Linux distributions only include 3.01 or earlier versions, and Ubuntu installs 'poppler' instead of xpdf which isn't compatible. Type pdftoppm -? to check - if the help message mentions poppler or anything other than 'xpdf-3.03' you should install the latest precompiled xpdf binaries direct from the xpdf authors:

There are precompiled binaries available from the XPDF authors at XPDF downloads - for linux, the one to pick is xpdfbin-linux-3.03.tar.gz which is statically linked to the necessary font libraries for rendering TrueType fonts correctly - if you find that uploaded PDFs have font problems, then your version of xpdf is probably substituting approximate built in fonts rather than using the right embedded TrueType font. The quickest way to solve this issue can be to download and use the precompiled xpdf binaries - setting $xpdfdir to the path you extract them to in the phpconfig.inc file (see step 4 below). 

  # To use the pre-compiled version of XPDF from www.foolabs.com:
  % mkdir /usr/local/bin/xpdf
  % cd /usr/local/bin/xpdf
  % wget ftp://ftp.foolabs.com/pub/xpdf/xpdfbin-linux-3.03.tar.gz
  % tar xvfz xpdfbin-linux-3.03.tar.gz
  # ... and then set $xpdfdir='/usr/local/bin/xpdf/xpdfbin-linux-3.03/bin64/';
  #  (or /bin32/ for 32-bit systems)
  #     in php/phpconfig.inc (see step 4 below)

Step 3: Compiling the custom version of pdftotext

Annotate requires a modified version of the standard 'pdftotext' utility supplied with the xpdf set of tools. You will need the standard gnu c++ compiler installed: 

  # as root...
... g++ probably already installed, if not (on Fedora):
  % yum install gcc
  % yum install gcc-c++

... (on Ubuntu):
  % sudo apt-get install g++

To extract and compile it, cd to where you extracted the annotate-server-3.x.x.tgz and: 

  # as annotate user...
  $ cd /var/www/html/annotate
  $ make xpdf

This will compile the pdftotext executable into: 

  ./xpdf-3.02/xpdf/pdftotext
which you can try running to check it has compiled ok. Running pdftotext with no arguments should print out version and help information. If all is well, you can go to Step 4.

If there were any compile errors building xpdf, you may find it useful to try the manual compile steps below: 

  # as the annotate user ...
  $ cd /var/www/html/annotate
  $ tar xvfz xpdf-3.02-annotate.tgz
  $ cd xpdf-3.02
  $ ./configure
  $ make pdftotext

Note that compiling pdftotext is simpler than compiling the X based xpdf tools as there are fewer dependencies; see the xpdf home page for more instructions.

Step 4: Create the 'php/phpconfig.inc' configuration file

You need to copy a sample configuration file to 'php/phpconfig.inc' and edit the settings to match your installation. A sample for Linux is provided in 'php/phpconfig-linux.inc'; for windows in 'phpconfig-windows.inc' and for Mac OSX in 'phpconfig-macosx.inc'. 

  $ cd /var/www/html/annotate/php
  $ cp phpconfig-linux.inc phpconfig.inc

The settings for the server are specified in the 'php/phpconfig.inc' file in the php subdirectory. If you have installed to http://yoursite.com/annotate/, your license is 1234-2222-3333-4444, and your email is joe@yoursite.com, you should edit the values to: 

  $nnotatesite = "yoursite.com";
  $nnotatepath = "http://yoursite.com/annotate";
  $licensecode = "1234-2222-3333-4444";
  $adminusers  = array("joe@yoursite.com");

You may also need to edit the paths to the utilities if they aren't in /usr/bin (see the comments in the php/phpconfig.inc for details).

[Note for Mac OSX users: copy the sample provided in phpconfig-macosx.inc to phpconfig.inc before editing - see guide] 

  // A.nnotate will look in $xpdfdir for the 'pdftoppm' and 'pdfinfo' utilities:
  $xpdfdir = "/usr/bin/";
  $infocommand  = "$xpdfdir/pdfinfo";
  $ppmcommand   = "$xpdfdir/pdftoppm";

  // The $wordscommand needs to be set to point to the A.nnotate 
  // version of pdftotext you compiled in the step above:
  $wordscommand = "/var/www/html/annotate/xpdf-3.02/xpdf/pdftotext -enc UTF-8 -raw";

  // Paths for image conversion utils.
  $pnmquant = "/usr/bin/pnmquant";
  $giftopnm = "/usr/bin/giftopnm";
  $pngtopnm = "/usr/bin/pngtopnm";
  $ppmtogif = "/usr/bin/ppmtogif";
  $ppmtopng = "/usr/bin/ppmtopng";
  $pamfile  = "/usr/bin/pamfile";
  $pnmscale = "/usr/bin/pnmscale";
  $curl     = "/usr/bin/curl";

If you are installing to a server which does not have internet access (e.g. on a virtual machine without internet connectivity) you will need to set the email configuration flags to disable sending emails on new accounts: 

$mailsender="none";
$noNewAccountEmail = 1;

Step 5: Check the settings

You can test the config settings and xpdf install from the command line; if there are any problems with the paths / installation, the error messages here should be easier to debug than when viewing via a web browser: 

  % cd php
  % php test_install.php

    # sample output:
    Words listed in test.txt
    Image of page 1 should be in: test-000001.png


  ## If you get a message like 'php is currently not installed'
  ## you need to install the command line version of PHP. On 
  ## ubuntu you can fetch this with:
  % sudo apt-get install php5-cli

This runs the utilities on a 'test.pdf' file, and extracts the words to 'test.txt', and makes a PNG image of the first page. If this doesn't work, check the php/phpconfig.inc settings. If the image of the first page is not produced correctly, it is worth checking that you have the latest version of the pdftoppm utility installed: it should be version 3.02 or later. Type pdftoppm -? to check. If it is something other than 3.02 or 3.03, you can either upgrade your installation (using yum upgrade xpdf) or simply download the latest binaries from www.foolabs.com/xpdf/download.html and change the path in phpconfig.inc to something like 

   $xpdfdir = "/mnt/install/downloads/xpdfbin-linux-3.03/";

Hint: make a safe copy of the phpconfig.inc file in case you overwrite it!

Step 6: View the welcome / index page

At this point, you should be able to open your browser at somewhere like: 

  http://yoursite.com/annotate/index.php

to see the welcome page. If it doesn't display, check you have set up apache / php correctly. You can also open your browser on 

  http://yoursite.com/annotate/php/phpinfo.php

to display the php installation information.

You will see a red message at the bottom of the page like: "No license found with code:1111-2222-3333-4444". This is because you need to validate your license with details from the main a.nnotate.com site (step 7 below) - but first you need to register an admin user account.

Click the 'Register' button to create an account, using the administrator email you specified in the $adminusers array in the phpconfig.inc file. You should see the documents page, with a sample document. If you do not, check again that you typed make install correctly above; the likely cause is that the private/ and docs/ subdirectories have not been created with the right permissions.

You should be able to view the sample 'welcome.pdf' document, and attach notes.

If there are any problems, point your browser at the settings check page (added in v3.1.9, Jul 2010) to run the installation diagnostic tests: 

  http://yoursite.com/annotate/check.html

Step 7: Validate the license

Visit your account page (the account link in the menu bar). It should show a message to 'Click to install license code: 1234-1111-2222-3333'. Click on this link to validate and install the license from the main a.nnotate.com site. If the code is not correct, check the setting in your phpconfig.inc file. If you do not yet have a license code, contact support [at] nnotate.com to obtain one.

Note that license validation requires internet access; if you need to install a.nnotate on a server which isn't on the internet, you'll need to install the license manually; contact support [at] nnotate.com for details.

Step 8: Try uploading a sample PDF

Go to your documents page, and click the 'Upload a new document' link, and choose a small pdf file, to check it can be uploaded and annotated.

Troubleshooting: if the pdf page is shown, but text highlighting is not working, then there could be a problem with running the custom pdftotext specified in php/phpconfig.inc. If no pdf page is displayed, check that the sample PNG image was generated in step 5 and double-check the paths to the pdftoppm utilities.

Step 9: Inviting new users to set up accounts.

New users can sign up as annotators using the register button on the index page (which you can get to by clicking on the 'A.nnotate' icon in the top left of any page, see also Step 6 above). As the administrator, you can upgrade them to become full users by hand, using the 'server admin' link in your account page. The account page also includes a link which you can send out by email to authorise people to register as licensed users on your server.

Step 10: Verify your mail setup

Your A.nnotate server sends out emails to new users, and for password reminders, using either the standard php mail() function, or using a web service on the main a.nnotate.com site. By default it uses the a.nnotate.com service (which sends messages from the automated account auto@nnotate.com) which will be enabled once you have installed your license; you can change this by editing the php/phpconfig.inc setting below: 

  $mailsender = $annotatesite;  // use a.nnotate.com service for sending reminders
  // $mailsender = "local";     // uncomment to use local PHP mail() function
  // $mailsender = "none";      // uncomment to disable mail sending.

If you use the local mail() sender, and are not getting any mail messages from your server, check your PHP configuration is set up correctly. (see php.ini settings) and it may also be worth checking your junk mail folder in case the automated messages are being classed as spam.

It is possible to use A.nnotate without enabling your server to send emails, but you will want to change your password on the account page to something memorable, as password reminders are only sent by email.

Note: Custom Integration with existing systems

If you are interested in integrating the A.nnotate system with your existing user authentication or content management systems, please contact us to discuss your requirements; the A.nnotate API allows you to control most aspects of the A.nnotate server to enable it to be used as an annotation component within your own web application.

Sample 1: Embedding an A.nnotate panel in your own web application

There is a sample page at php/sample-proof.php live demo which demonstrates how to embed an A.nnotate view of a PDF panel in an iframe. Clients can add comments without needing an account, and your in-house team can access and deal with the suggestions. See the Guide to embedding an A.nnotate panel within your own web application for more details.

Note: Upgrading your installation (e.g. from 3.1.19 to 3.1.30)

For minor upgrades, you can simply unpack the server in the same directory, but make sure you take backup copies of the configuration files first (php/phpconfig.inc, scripts/*.inc), as they will be overwritten. The steps should be something like: 

# in the directory where you extracted the previous annotate-server.*.tgz...
mkdir bak-dec22

# take a backup of the config files first:
cp php/*.inc scripts/*.inc bak-dec22

# unpack the new version of the server
tar xvfz annotate-server-3.x.x.tgz

# restore the config files
cp bak-dec22/phpconfig.inc php/

# You might need to edit the paths in phpconfig.inc if not installing
# to the same folder - and possibly update the scripts/*.inc files
# from the backups if you've installed the optional modules.

Version history

The notes below list changes included with particular releases: 

v3.1.30 [Mar 2015]
 - minor maintenance: fix for IE11

v3.1.29 [Jun 2013] 
 - minor maintenance release; some fixes for webkit layout; 
 - new view-only page

[Jan 2013]
 - updated xpdf links for 3.03 binaries (which fix some occasional PDF rendering bugs)

v3.1.19 [Jan 2011]
 - minor bug fix for sharing links to externalhtml pages

v3.1.17 [Nov 2010]
 - admin screen fix for emails with + char
 - fix for out of credit message if !linkSharable
 
v3.1.16 [29 Oct 2010]
 - minor lang additions for email notifications
 - config option for single line status and main menu colors
 - beta of revisions support and differences between pdf documents
 - bug fix for display of sharable link checkbox user default

v3.1.15 [Oct 2010]
 - extra hide= config options for page chooser and zoom
 - extra lang options for multi-language admin pages
 - paypal and credits config options for multiple groups
 - minor bug fix for link annotation tooltip
 - config option for note font size
 - api routines for adding contacts

v3.1.13 [Sep 2010]
 - developer preview of upcoming features:
   * HTTPS support
   * $plainNotesOnly config option
   * multi-language support for account, admin pages, emails etc
   * support for exporting PDFs with annotations in Chinese, Japanese, Korean
   * IE bug fix for running on external websites 
   * Export full size PDF with handdrawn notes


v.3.1.9 [Jul 2010]
 - Major new 3.1 release:
   * support for user-defined translations (see a.nnotate.com/translations.html )
   * first public release of hand-drawn annotations
   * beta version of rich-text annotation editor
   * documentum taskspace module update to avoid using unreliable ACS server
   * extra API calls, config options
   * option to include note timestamps in exported PDF
   * support for PHP5.3 (earlier releases required PHP5.2)


v.3.1.8 [Jun 2010]
 - freehand annotation in a popup (developer preview)

v.3.1.7 [May 2010]
 - initial version with tablet handwriting support

v.3.1.6 [May 2010]
 - upgrade no longer overwrites phpconfig.inc settings
 

v.3.1.4 [24 Mar 2010]
 - if allowDownload=false, copy disallowed too
 - $hideNotesHidesMarks=1 config option to hide page marks
 - View menu added to show just own or everyone's notes
 - Tools - plain notes used view menu settings to print or export
   own or all notes

v.3.1.3 [28 Feb 2010]
 - added support for use as Documentum plugin, storing 
   annotations in external repository
 - improved PDF export with notes

v.3.1.2 [14 Feb 2010]
 - minor fix to remove duplicates for Moodle module

v.3.1.1 [10 Feb 2010]
 - First release of 3.1.
 - Major new features:
   * Document reviews:
     - 'Done' button on documents
     - customizable form for reviewers to complete
     - track review status on home page and document notes page
   * New page selector leaves more space for the document
   * New full page view mode (hide menu bar)
   * New note view selector (margin, footnotes)
   * Keyboard shortcuts:
     - PageUp, PageDown to change pages
     - ctrl-Enter to save a note
   * Support for translations of user interface (Greek, Norwegian etc)
   * Extra security options:
     - restrict document to access list of users
     - folder sharing invitations expire after single use
     - option to prevent download of original document
   * Performance improvements:
     - faster document index loading speed with 1000s of documents.
   * TIFF, BMP support
   * Option to convert uploaded images to PDF 
   * Windows server version supports openoffice


v.3.0.29 [16 Sep 2009]
 - extra config options for account page
 - improved hideEmailAddresses option
 - added file versioning info in php/_versioninfo.txt 

v.3.0.28 [12 Aug 2009]
 - added arrows to image notes
 - page previews now movable

v.3.0.26 [22 July 2009]
 - added extra page zoom controls

v.3.0.25 [22 June 2009]
 - fixes for IE8 text highlighting
 - fixed issue with Clipboard dialog

v.3.0.23 [23 May 2009]
 - added 'link to note' dialog
 - added 'send note to Twitter' option
 - added Publish : generate guest link button
 - fixed preview for landscape PDFs
 - updates for sentences attachment dialog

v.3.0.22 [May 2009]
 - added anyEdit flag to phpconfig.inc to allow people to edit others' comments
 - improved matching of sentences to selected text
 - separate downloads for version with / without api access

v.3.0.20 [Apr 2009]
 - fixed cross site 'Permission denied' problem embedding pdfnotate in iframe
 - openoffice fix for uploading .txt files 
 - minor update to pdftotext utility for handling embedded tab chars 

v.3.0.19 [Apr 2009]
 - fix for starting new html text selection when haven't cancelled first
 - fix for safari refresh problem on snapshots
 - added noLocationChange option to phpconfig to avoid setting #note123
 - fix for delete note problem updating display
 - added config option for api clock skew
 - document properties notes text area fix
 - pdf page controls at bottom of page now jump to top

v.3.0.18 [Mar 2009]
 - workaround for IE7's javascript loading bugs when running 
   a.nnotate on external sites with replacement GUI

v3.0.17 [Mar 2009]
 - sentences GUI for re-attaching notes now has match: option

v3.0.16 [Mar 2009]
 - support for overlapping annotations in HTML
 - custom notebox / note rendering on PDFs on external sites

v3.0.14 [Mar 2009]
 - notes can now contain html
 - account page now has option for default note style (margin, hidden)
 - API improvements:
 -    extra callback options for uploadDocument call
 -    API sample now includes code using curl to POST documents
 -    document metadata can include custom fields e.g. x_myfield
 -    extra options to hide GUI components (gripbar) from pdfnotate.php
 -    notes can now have optional linkTo and linkTitle fields
 -    one-by-one option for showing one note at a time
 -    extra phpconfig options: 
 -      exported PDF can have custom footer
 -      can switch off emails on new accounts

v3.0.11 [12 Feb 2009]
 - added $authorOnlyEdit flag to phpconfig to control
   whether document owner can edit notes by other people.

v3.0.10 [Feb 2009]
 - a fix for a bug with the listDocuments.php API call
 - fix for annotating html snapshots for Safari
 - support for early access Windows (win32 / IIS) version
   --- please contact us if you need the win32 version ---
 - fixes perPagePermissions issue with note replies

v3.0.3 [Jan 2009]
 - fixes a configuration issue for fileuploadcgibin for
   enabling the file upload progress bar module
 - fixes perPagePermissions issue in API

v3.0.2 [Dec 2008]
 - major new version supporting folders and image annotation

Next steps...

If you have got this far, then congratulations! You should have a working A.nnotate server for collaborating on PDF documents and snapshots of web pages.

You can upgrade your installation to support annotating Word / OpenOffice documents, display thumbnails of snapshots of web pages, and display a progress bar during file upload by enabling a number of optional modules. See the Part 2: Install A.nnotate Modules guide for details.

Please email any questions to support [at] nnotate.com.