Annotate Server Installation Guide - Ubuntu 16.04

This section explains how to install the Annotate server on your own hardware. It assumes you are familiar with command line access to a Linux web server. There is also a guide for CentOS which can be used with RedHat based distributions. If you are not using Linux, see the install guide for Windows or Mac.

This guide describes how to install version 5.1.1 of the Annotate server for Linux (released Oct 2017).

This chapter describes the steps needed to get a basic install of the Annotate V5 server up and running on your server. This will work for annotating uploaded PDF documents. There are also a number of optional modules you can install once the basic system is up and running, including support for Word and OpenOffice documents: see Part 2: Installing Annotate modules for details once you have followed the steps below.

1. Apache 2.4, PHP 7 and dependencies

To install annotate V5 on a linux server, you'll need SSH login access as root. The basic packages needed are below:

  • A Linux server to which you have SSH access
  • Apache 2.4; PHP 7; Java 8
  • standard linux utilities: make, zip, diff, curl, perl
  • standard image and pdf utilities: netpbm, xpdf

For ubuntu 16.04:

# ensure you have the basic tools installed (make, zip, java)
# first login as root; or 'sudo su'.

% apt-get install zip make diffutils apache2 php7.0 curl perl
% apt-get install openjdk-8-jre-headless
% apt-get install netpbm libnetpbm10 libnetpbm10-dev xpdf curl pngquant libtiff-tools

% service apache2 restart

To check your web server, check you can view a test page on
your server's IP address, e.g.  http://192.168.0.123

You can also add a test file to your web space like 'test.php'
containing the single line below:
<?php phpinfo(); ?>
then view http://192.168.0.123/test.php in a browser to check that 
PHP is enabled.
                    

You also need to edit the php configuration values in php.ini: on ubuntu this is stored in /etc/php/7.0/apache2/php.ini: edit these with your preferred editor. Suggested values are below: the default file upload limit on ubuntu is only 2Mbytes, so increasing the upload_max_filesize to the largest PDF you need to handle is recommended. The default memory_limit per script is low (128M) so this is worth increasing to 400M or greater.

; edit the /etc/php/7.0/apache2/php.ini values :
max_execution_time = 300
max_input_time = 60    
memory_limit = 400M    
post_max_size = 100M
upload_max_filesize = 100M
                    
# login as root and restart apache after editing php.ini to apply the changes.
# 

  % sudo service apache2 restart

# You can check the current value of these settings by viewing
# the phpinfo() script you created above (e.g. http://192.168.0.123/test.php) 
                    

Apache configuration settings

You need to configure your Apache server to enable .htaccess security controls; on Ubuntu, this is stored in /etc/apache2/sites-enabled/000-defaults). In the <Directory> section which points to the root of your web server, make sure that AllowOverride All is set (on Ubuntu it is set to "None" by default).

# Edit the apache configuration for your www folder.
# AllowOverride needs to go from "None" to "All"
# and also switch "Indexes" and "Multiviews" flags
# to "-Indexes" and "-MultiViews" to switch off

  % sudo nano /etc/apache2/sites-enabled/000-defaults

 <Directory /var/www/>
   Options -Indexes +FollowSymLinks -MultiViews
   AllowOverride All
   Require all granted
 </Directory>
                    

You also need to enable the following apache modules which optimize compression and caches:

# Ensure required apache modules are enabled:
% a2enmod headers deflate expires rewrite 
                    

2. Download and unpack the code

The Annotate code is written in PHP and Java, with the user interface written in Javascript code; the download below includes everything you need to get set up.

A password is required to access the download link; this will be supplied with your license contract.

Please note that the code is copyright Textensor Limited (apart from the pdf binaries which are distributed under a GNU license, based on the XPDF codebase). If you install it for production use, you must purchase a license.

The steps below assume you are installing to the /var/lib/annotate/a511/ directory as the user "annotate".

# as root, create a new 'annotate' user for the install:
% adduser annotate
% mkdir -p /var/lib/annotate
% chown annotate:annotate /var/lib/annotate
% su annotate
% mkdir -p /var/lib/annotate/a511


# as the 'annotate' user:
                                 
### If you are reinstalling, make a safe copy of any edited files before unpacking ###
# ... move the downloaded annotate-server-5.1.1.zip file here...
$ cd /var/lib/annotate/a511
$ unzip annotate-server-5.1.1.zip
$ make install
# this creates the data directories
                    

The server unpacks within the current /var/lib/annotate/a511 directory.

    
    makefile                           # install scripts
    www/                               # the annotate javascript and php
    php/                               # the annotate server code

    bin/                               # binaries for converting pdfs to images and text
    util/                              # installation utilities and samples
    scripts/                           # scripts for running openoffice 
    cgi-bin/                           # cgi scripts for file upload progress (optional)

# User data is stored in the folders below:
    docs/                              # web directory for serving page images 
    private/                           # private data directory for notes
                    

3. Link to annotate web folder from Apache

You need to configure your apache server to serve up the contents of the /var/lib/annotate/a511/www/ folder; one way to do this is just make a softlink from /var/www/annotate to this folder:

# Make a link from the /var/www default apache web area to your
# annotate installation:

 % ln -s /var/lib/annotate/a511/www /var/www/annotate

# After this, you should be able to view in a browser (e.g.): 
  http://192.168.0.123/annotate/index.php
                    

4. Edit 'php/phpconfig.inc' file

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

# log in as annotate user:
$ cd /var/lib/annotate/a511/www/php
$ cp phpconfig-linux.inc phpconfig.inc

# edit the phpconfig.inc file:
$ nano phpconfig.inc
                    

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 phpconfig.inc values to:

  
$nnotatesite = "yoursite.com";
$nnotatepath = "http://yoursite.com/annotate";
$licensecode = "1234-2222-3333-4444";
$adminusers  = array("joe@yoursite.com");
                    
  
// Check the below settings if you've installed somewhere other than /var/lib/annotate5/:
$annotatebindir = "/var/lib/annotate/a511/bin/";
$privatedir = "/var/lib/annotate/a511/private/";

// The default is set up for a 64-bit linux install;
// if on a 32-bit system, uncomment the line below:
// $pdftoimagerot = $annotatebindir."pdftoimage-rot32";
                    

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;
                    

5. Check the settings

Visit http://yourserver.com/annotate/check.html to run the built-in tests. This should show if there are any obvious configuration issues.

6. View 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.

Click the 'Register' link and sign up a new account using the admin email you specified in phpconfig.inc (the $adminusers setting).

7. Validate the license

Visit your account page (the account link, or your name in the banner). 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, get in touch here.

Note that license validation requires internet access; if you need to install annotate on a server which isn't on the internet, you'll need to install the license manually; contact support here..

8. Upload a sample PDF

Visit the workspaces page that you see on login (http://yoursite.com/annotate /php/workspaces.php) and use the 'Create New Workspace' button to create a new workspace, then 'Add document' to upload 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, or if no pdf page is displayed, check that the sample PNG image was generated in step 5 and double-check the paths in the phpconfig.inc file.

9. Inviting new users to set up accounts

You can add new users to a workspace from the "Admin" tab. They can also sign up for themselves using the 'register' link available from the index page (e.g. 192.168.0.123/annotate/index.php).

10. Verify your email setup

Your Annotate 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 = "a.nnotate.com"; // 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 Annotate without enabling your server to send emails, but you will want to set your password on the account page to something memorable, as password reminders are only sent by email.

Next steps - adding optional modules

If you have got this far, then congratulations! You should have a working Annotate server for collaborating on PDF documents.

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

Questions / problems:

Please get in touch here.