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.
This guide describes how to install version 6.0 of the Annotate server for Linux (released Oct 2020).
This chapter describes the steps needed to get a basic install of the Annotate V6 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.4 and dependencies
To install Annotate 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.4; Java 8
- standard linux utilities: make, zip, diffutils, curl, perl
- standard image and pdf utilities: netpbm, pngquant, imagemagick, tesseract
For ubuntu 20.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.4 php7.4-curl curl perl php-mbstring
% apt-get install openjdk-8-jre-headless
% apt-get install netpbm libnetpbm10 libnetpbm10-dev curl pngquant libtiff-tools
# manual xpdf installation
% wget http://security.ubuntu.com/ubuntu/pool/main/p/poppler/libpoppler73_0.62.0-2ubuntu2.12_amd64.deb
% apt-get install ./libpoppler73_0.62.0-2ubuntu2.12_amd64.deb
% wget http://archive.ubuntu.com/ubuntu/pool/universe/x/xpdf/xpdf_3.04-7_amd64.deb
% apt-get install ./xpdf_3.04-7_amd64.deb
% 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.4/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.4/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-default.conf). 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-default.conf
<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.
- Annotate V6 server, including API and linux binaries: annotate-server-6.0.zip
Please note that the code is copyright Annotate Software 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/a60/ 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/a60
# as the 'annotate' user:
### If you are reinstalling, make a safe copy of any edited files before unpacking ###
# ... move the downloaded annotate-server-6.0.zip file here...
$ cd /var/lib/annotate/a60
$ unzip annotate-server-6.0.zip
$ make install
# this creates the data directories
The server unpacks within the current /var/lib/annotate/a60 directory.
makefile # install scripts
www/ # annotate javascript and php
realtime/ # annotate realtime module (optional)
search/ # annotate search module (optional)
bin/ # binaries for converting pdfs to images and text
util/ # installation utilities and samples
scripts/ # scripts for running openoffice/aspose
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/a60/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/a60/www /var/www/html/annotate
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/a60/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/a60/bin/";
$privatedir = "/var/lib/annotate/a60/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) omit step 5 and set the email configuration flags to disable sending emails on new accounts:
$mailsender="none";
$noNewAccountEmail = 1;
5. 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.
6. Visit login page
At this point, you should be able to open your browser at somewhere like:
http://yoursite.com/annotate/php/signin.php
to see the welcome page. If it doesn't display, check you have set up apache / php correctly.
Visit the link below to create a new account using the admin email you specified in phpconfig.inc (the $adminusers setting).
http://yoursite.com/annotate/php/register.php
7. Validate the license
Visit your subscription page (top-right username dropdown). 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 at support@annotate.com.
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.
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.
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 and other features by enabling a number of optional modules. See the Part 2: Install Annotate Modules guide for details. For search and realtime the annotate server zip contains a /search and /realtime folder with instructions.
Questions / problems:
Please contact us at support@annotate.com.
