 |
| PDF Annotation |
| Image Annotation |
| Collaboration |
| Document Management |
| Web Research |
| CMS Annotation |
| Document Viewing |
| E-learning |
 |
A.nnotate Server Installation Guide for Windows servers
This chapter includes instructions for installing your own version of the A.nnotate server for IIS or Apache on Windows. Note that these instructions include support for annotating PDF files only - you may wish to also see the guide for installing on Linux as this guide just covers the windows specifics.
This chapter describes how to install version 3 of the A.nnotate server on windows (v3.1.19 updated Feb 2011).
Prerequisites
Before you install A.nnotate, you need to have a web server running PHP5 - we have run it on IIS (v5.1) and Apache. The instructions here are given for Windows XP and either IIS 5.1 or Apache 2.2. Some settings are different for IIS and Apache installations; these are marked [IIS only] or [Apache only] below.
[Apache only] Notes on installing PHP5 and Apache on Windows
There are a number of guides for installing Apache and PHP on Windows - the notes below show the basic steps:
Step 1: Default installation of Apache - from: http://httpd.apache.org
Step 2: Download php zip file, extract it to your C: drive under c:\php5\
Step 3: Edit httpd.conf located in the Apache web server installation folder:
c:\Program Files\Apache Software Foundation\Apache2.2\conf\httpd.conf
Add these lines....
LoadModule php5_module "c:/php5/php5apache2_2.dll"
AddType application/x-httpd-php .php
In the <Directory "C:/Apache Software / [...] /htdocs"> section, change:
AllowOverride All
(this enables .htaccess support for directory security)
Step 4: Goto c:\php5\ installation directory,
copy php.ini-dist c:\WINDOWS\php.ini
(edit this file too - see the PHP configuration section below.)
[IIS only] Notes on installing PHP5 and IIS on Windows
Updated March 2012: Guide to install annotate on windows 7 and IIS 7
There are many guides on the internet to installing IIS on windows servers, e.g. see Installing IIS on Windows XP (external) To get php5 running with IIS, download the .zip version and unpack it into a directory like c:\php5 You need to create a 'php.ini' file - the standard PHP distribution includes samples for development / production use and you may wish to start with the php.ini-dist version, as this will generate error messages in case anything goes wrong with the install. Some settings of the php.ini file you should check:
PHP Configuration
The standard PHP comes with some suggested configuration files in c:\php5\php.ini-dist; you need to copy this to c:\windows\php.ini and edit the settings. Particular options to check are below:
; Some settings to check / edit in your php.ini file (e.g. c:\php5\php.ini or c:\windows\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
You can check whether you have the correct version of your web server / 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.
Download the A.nnotate server code
You can download the a.nnotate server code for windows from : A password is required to access the download links; this will be supplied when you purchase a license. The links below contain all code necessary to run a local installation of A.nnotate. The first download link also includes the API.
- A.nnotate server for win32 plus integration API: annotate-server-and-api-win32-3.1.19.zip
- A.nnotate server for win32 (no api included): annotate-server-win32-3.1.19.zip
(We recommend you use the latest version above; however some earlier versions are also available: v3.1.15 (Oct 2010) v3.1.9 (Jul 2010) v3.1.3 (Feb 2010) and v3.0.28 (Sept 2009) and v3.0.28 with api.)
You should create a new folder on your server to extract it to - e.g. "c:\website\annotate\", or for Apache "c:\Program Files\Apache...\Apache2.2\htdocs\annotate". The zip file extracts a directory structure as shown below.
index.php
...
js/ # the annotate javascript
css/ # CSS styles
img/ # images
php/ # the annotate server code
docs/ # public web-readable directory
private/ # private data directory
win32/ # windows executables for conversions
[Apache only] Linking to A.nnotate from Apache
You can unpack a.nnotate into the default document root, e.g. c:\Program Files\Apache...\Apache2.2\htdocs\annotate - or unpack elsewhere and change the httpd.conf DocumentRoot path and settings.
You also need to copy the sample htaccess files into the docs/ and private/ folders for security:
// cd to your annotate/ installation folder: copy htaccess-noindex.txt .htaccess copy htaccess-private.txt private\.htaccess
[IIS only] Linking to A.nnotate from IIS
To link to your a.nnotate installation, you can
open up the IIS admin interface (Control Panel > Administrative Tools
> Internet Information Services), right-click on 'Default Website',
and select New > Virtual Directory ...
To create a
new top level link to your annotate installation
like "http://localhost/annotate/" enter 'annotate'
when prompted for the Alias, and browser to your install location
(e.g. c:\website\annotate). You should set the permissions
to allow 'scripts / executables':
You can then configure the details of the 'annotate/' virtual
directory by right-clicking on it in the IIS admin window and
viewing Properties.
You need to enable PHP; click the Configuration...
button on the properties dialog to show the application mappings:
To add '.php' as a file extension for running PHP, click Add:
Browse to the PHP / IIS DLL which will be located somewhere like "c:\php5\php5isapi.dll" and enter ".php" as the extension. You can also remove all the other script mappings (.asp etc) as they are not needed for A.nnotate.
You also need to remove web read access to the private/ folder. Right-click on the private/ folder in the IIS admin page, view the Properties and uncheck the 'Read' permission checkbox.
Edit the configuration settings in 'php/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 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 also need to set the full path to the win32/ folder so the PHP scripts can find the executables for converting PDFs to images and text, e.g.:
$win32bin = "c:/website/annotate/win32/";
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;
[IIS Only] Allow the PHP user to run the executables
You can choose to run IIS on another TCP port, e.g. right-click on 'Default Websites > Properties' and change the value of TCP Port (e.g. to 8888). If you do this, then change the settings in phpconfig.inc too - e.g.:
// if running web server on port 8888, change the settings as below: $nnotatesite = "yoursite.com:8888"; $nnotatepath = "http://yoursite.com:8888/annotate";
IIS is usually set up to run scripts as a limited user account named something like "IUSR_JOE" (if your server is named "JOE"). You can find out/ edit the user account IIS uses as the web user by right-clicking on the IIS annotate/ folder and going to Properties > Directory Security > Edit... which displays the anon user account details.
The PHP user needs to be able to run the .exe programs in the win32/ folder.
[ on a Windows command prompt: if your machine name is 'JOE' and your IIS user is 'IUSR_JOE', you can enable PHP to run the conversion programs needed for A.nnotate using : ] C:> cd \WINDOWS\system32 C:\windows\system32> cacls cmd.exe /E /G JOE\IUSR_JOE:R
Set the directory permissions to permit the PHP user to store documents
The PHP user needs to be able to write to the docs/ and private/ folders, which are used to store documents and notes. There is an install.bat file which sets these folders up; start a windows command prompt and run it using:
C:> cd \website\annotate C:> install.bat
Test you can create the admin account
At this point you should be able to point your browser somewhere like http://localhost/annotate/index.php to see the welcome page. Click the 'Register' button and enter the admin email you used in the phpconfig.php file to create the admin account. You should be able to view the sample document and add notes - if there are problems, it is probably caused by permissions - so check the settings in the IIS admin page and also use the cacls command line utility to check the IIS user has write permissions on the private/ and docs/ folders.
Before you can add more users, you need to install your license; see the link in your 'Account' page.
Test the installation of the executables / permissions
There is a test PHP script in win32/test.php which runs all the executables to convert a PDF into images and extracts the text. You can run this by pointing your browser at: http://localhost/annotate/win32/test.php If all is well, you should see an image at the end, and a sequence of 'SUCCESS' messages as each program runs. You can also run this PHP from the command line (e.g. 'php test.php') which can be useful for diagnosing problems.
Test uploading a small PDF file
If the previous test worked, you should now be able to upload a PDF file from your 'documents' page. Note that thumbnails are not yet generated on windows installations of the server.
Adding support for uploading DOC, PPT, XLS etc using OpenOffice
To add support for uploading Office formats on Windows, you need to install OpenOffice 3 on the server: openoffice.org.
OpenOffice needs to be running in the background in server mode. You need to stop the quickstarter running the interactive version (right-click on the quickstart icon, and uncheck the 'load openoffice during system startup' box). There is a script for starting and stopping it in:
C:> cd \website\annotate\win32 # to stop it: C:> start oowin32.bat stop # to start openoffice in server mode: C:> start oowin32.bat start # to try a test conversion: C:> start oowin32.bat convert DocumentConverter.py simple.doc simple.pdf
Then uncomment the line in php/phpconfig.inc to enable conversions:
$ooshcommand="echo off & \"".$win32bin."oowin32.bat\" convert \"".$win32bin."DocumentConverter.py\"";
At this point, you should be able to upload a sample DOC file on your A.nnotate documents page, and it will be converted first to PDF (using openoffice), then shown in the browser.
To ensure that openoffice is running in server mode all the time, you can set up a new scheduled task using Start - Control Panel - Scheduled Tasks - Add scheduled task. ( or on Windows 7: Start - search for 'task' - Task Scheduler ). Browse for the OpenOffice executable ('soffice.exe') and append the arguments below to start it in server mode:
C:\PROGRA~1\OPENOF~1.ORG\program\soffice.exe -accept="socket,port=8100;urp;" -norestore -nofirststartwizard -headless -nologo
You can schedule it to start at login, or every 10 minutes (in which case it will restart openoffice if the process dies for any reason). On Windows XP you will need to enter the user name and password to run openoffice as (so your account will need a password), and the user you choose needs to have write access to the annotate docs/ folder.
You can check whether openoffice is running in the background using Task Manager, and looking for the 'soffice.exe' and 'soffice.bin' processes.
Windows 7 configuration notes
A default windows 7 install will hide file extensions which can be confusing. (e.g. "httpd.conf" will be shown as "httpd"). You can shown them with Organize - Folder and search options - View tab - and uncheck: Hide extensions for known file types.
Use Icacls in place of cacls to change permissions - or grant full control of Users to htdocs/annotate/.
Uncomment the lines below in httpd.conf to enable apache caching headers.
LoadModule expires_module modules/mod_expires.so LoadModule headers_module modules/mod_headers.so
To enable web connections from outside in Windows 7 firewall: Control panel - Windows firewall - Advanced settings - Inbound rules - new rule - Port 80 - allow.
If you just see a "Loading..." spinning disk and no notes shown, check that the URL settings (in $nnotatepath and $nnotatesite) are correct - this can be caused if it is trying to fetch from an unreachable server.
Please email any questions to support [at] nnotate.com.