A.nnotate Server Installation Guide

This guide includes instructions for installing your own version of the A.nnotate server. It assumes you are familiar with command line access to a Linux web server.

Initial release: this guide describes the initial release of the A.nnotate server (v1.1.3 updated 6th Oct 2008) made available to selected developers.

This page 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.

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'.

  • A Linux server to which you have SSH access.
  • Apache
  • PHP 5 (with the JSON module enabled)
  • 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 on Fedora Linux, as root:
  % yum install php php-json

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

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 following file: (Password required - contact support [at] nnotate.com to request access)

Please note that the code is copyright Textensor Limited (apart from the xpdf code which is under a GNU license); you may use it for evaluation/development/test purposes only; if you install it for production use, you must purchase a license.

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:
  % 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-1.x.x.tgz file here...
  $ tar xvfz annotate-server-1.x.x.tgz
  $ make install                         # this creates the data directories

The server unpacks within the current directory. 

    index.php
    ...
    js/                                # the annotate javascript
    php/                               # the annotate server code
    oo/                                # 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.02  (for:  pdfinfo,  pdftoppm)
  netpbm, netpbm-progs, netpbm-devel     (for:  pnmquant, pamfile, ppmtogif)   
  curl

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: 

  # as root...
  ... e.g. on Fedora Linux:
  % yum install netpbm netpbm-progs netpbm-devel xpdf curl

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

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++

To extract and compile it, cd to where you extracted the annotate-server-1.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: Edit the 'php/config.tmp' file

The settings for the server are specified in the 'php/config.tmp' 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/config.tmp for details). 

  // XPDF commands
  $wordscommand = "/var/www/html/annotate/xpdf-3.02/xpdf/pdftotext -raw";
  $infocommand  = "/usr/local/bin/pdfinfo";
  $ppmcommand   = "/usr/local/bin/pdftoppm";

  // Paths for image conversion utils.
  $pnmquant = "/usr/bin/pnmquant";
  $ppmtogif = "/usr/bin/ppmtogif";
  $pamfile  = "/usr/bin/pamfile";

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.gif


  ## 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 GIF image of the first page. If this doesn't work, check the php/config.tmp 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. Type pdftoppm -? to check. If it is something other than 3.02, 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 config.tmp to something like 

   $xpdfdir = "/mnt/install/downloads/xpdf-3.02pl2-linux/";

Hint: make a safe copy of the config.tmp 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/phpinfo.php

to display the php installation information.

Click the 'Register' button to create an account, using the administrator email you specified in the $adminusers array in the config.tmp 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.

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 config.tmp file. If you do not yet have a license code, contact support [at] nnotate.com to obtain one.

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 instead of text highlighting the highlighting is of 'blocks', then there is a problem with running the custom pdftotext specified in php/config.tmp. If no pdf page is displayed, check that the sample gif 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/config.tmp setting below: 

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

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.

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.

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.

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.

© Textensor Limited 2008 All rights reserved. Privacy policy, Terms of use
A.nnotate is provided by Textensor Limited, Registered in Scotland, Company No. SC294230, +44(0)131 466 8356