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.
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.
- Step 1: Download and unpack the code
- Step 2: Installing the necessary xpdf and image utilities
- Step 3: Compiling the custom version of pdftotext
- Step 4: Edit the 'php/phpconfig.inc' file
- Step 5: Check the settings
- Step 6: View the welcome / index page
- Step 7: Validate the license
- Step 8: Upload a sample PDF
- Step 9: Inviting new users to set up accounts
- Step 10: Verify your mail setup
- Note: Integration with existing systems
- Note: Upgrading from earlier versions
- Note: Version history
- Next steps - adding Word / Office support
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.
- 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
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:
- A.nnotate server plus integration API: annotate-server-and-api-3.1.30.tgz
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.
'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/pdftotextwhich 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 email@example.com, you should edit the values to:
$nnotatesite = "yoursite.com"; $nnotatepath = "http://yoursite.com/annotate"; $licensecode = "1234-2222-3333-4444"; $adminusers = array("firstname.lastname@example.org");
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:
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
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:
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 email@example.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.
The notes below list changes included with particular releases:
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.