1. Install apache, php and dependencies
To install annotate V4 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; PHP; Java
- standard linux utilities: make, zip, diff, curl, perl
- standard image and pdf utilities: netpbm, xpdf
For CentOS7 :
# *NB* check if you have SELINUX enabled; if so the easiest
# way to enable annotate to run is just to disable it,
# as it prevents apache from running the pdf conversion tools
# and installing the license.
# (SELINUX OPTION 1) easy option: disable SELINUX:
% getenforce
# shows whether SELINUX is on: you can switch it off by editing:
% nano /etc/sysconfig/selinux
# and change SELINUX=enforcing to SELINUX=disabled
# *NB* you need to reboot after changing the selinux setting
# (SELINUX OPTION 2) fine-grained security option: set individual flags
# check /var/log/audit/audit.log for permission denials
# getsebool -a | grep http
# then selectively enable:
# setsebool httpd_can_network_connect on
# ... we recommend you get annotate running first without selinux,
# then add the fine grained security flags.
# Install pre-requisites:
# ensure you have the basic tools installed (make, zip, java)
# first login as root; or 'sudo su'.
% yum groupinstall base # for zip make diff curl perl
% yum install httpd php
% yum install java
% yum install netpbm netpbm-progs netpbm-devel curl ghostscript-fonts poppler
% service httpd 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
If you are not able to view the page, check that the CentOS firewall is not blocking
http traffic.
% firewall-cmd --list-all
'http' should be one of the enabled services. To add it in CentOS 7 with firewalld:
% firewall-cmd --permanent --zone=public --add-service=http
% firewall-cmd --reload
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 CentOS7 this is stored in /etc/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.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 httpd 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 CentOS7, this is stored in /etc/httpd/conf/httpd.conf). In the <Directory> section which points to the root of your web server (/var/www/html), 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/html>
Options -Indexes FollowSymLinks
AllowOverride All
Require all granted
</Directory>
The following apache modules which optimize compression and caches: headers deflate expires rewrite are enabled by default on centos; you can check the lines like LoadModule headers_module modules/mod_headers.so are not commented out in httpd.conf.
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 V4 server, including API and linux binaries: annotate-server-4.2.6
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.
The steps below assume you are installing to the /var/lib/annotate4/ directory as the user "annotate".
# as root, create a new 'annotate' user for the install: % adduser annotate % mkdir /var/lib/annotate4 % chown annotate:annotate /var/lib/annotate4 % su annotate # as the 'annotate' user: ### If you are reinstalling, make a safe copy of any edited files before unpacking ### # ... move the downloaded annotate-server-4.x.x.zip file here... $ cd /var/lib/annotate4 $ unzip annotate-server-4.x.x.zip $ make install # this creates the data directories
The server unpacks within the current /var/lib/annotate4/ 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 your annotate install from apache
You need to configure your apache server to serve up the contents of the /var/lib/annotate4/www/ folder; one way to do this is just make a softlink from /var/www/annotate4 to this folder:
# Make a link from the /var/www default apache web area to your
# annotate installation:
% ln -s /var/lib/annotate4/www /var/www/annotate4
# After this, you should be able to view in a browser (e.g.):
http://192.168.0.123/annotate4/index.php
4 Create the 'www/php/phpconfig.inc' configuration 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/annotate4/www/php
$ cp phpconfig-linux.inc phpconfig.inc
# edit the phpconfig.inc file:
$ nano phpconfig.inc
If you have installed to http://yoursite.com/annotate4/, 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/annotate4/:
$annotatebindir = "/var/lib/annotate4/bin/";
$privatedir = "/var/lib/annotate4/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/annotate4/check.html to run the built-in tests. This should show if there are any obvious configuration issues.
6. View the registration page and create the admin user account
At this point, you should be able to open your browser at somewhere like:
http://yoursite.com/annotate4/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, contact support [at] nnotate.com to obtain one.
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] nnotate.com for details.
8. Try creating a new workspace and uploading a test PDF
Visit the workspaces page that you see on login (http://yoursite.com/annotate4/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/annotate4/index.php).
10. Verify your mail 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...
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 contact us at support@annotate.com.
