Annotate server installation guide for Windows 7 + IIS servers

This chapter includes instructions for installing your own version of the Annotate server V4 on Windows.

The details are given for IIS 7 on Windows 7; it is also possible to install on other versions of Windows (e.g. Windows Server 2003) and to use Apache instead of IIS; the main prerequisite is a web server which can run PHP. See also the guide for installing on Linux.

This chapter describes how to install version 4 of the Annotate server on Windows 7 with IIS 7.

Notes on installing PHP5 and IIS 7 on Windows 7

The PHP manual includes instructions for setting up PHP and IIS; the recommended route is to run PHP with IIS is via FastCGI. You should refer to the guide above for details; along with the Microsoft IIS + PHP + FastCGI guide. An outline of the install sequence is below:

1. Install IIS 
   (Start - Control panel - Programs and features - 
    Turn Windows features on or off -
    Internet Information Services - 
      World Wide Web Services - 
        CGI, ISAPI Extensions, ISAPI Filters
      Web Management Tools - 
        IIS Management Console

   At this point you should be able to open a browser at http://localhost
   and see a splash screen.


2. Install PHP
   http://windows.php.net/download/

   Download a PHP Non-thread safe .zip file
     (the non-thread safe one is faster for a FastCGI installation).   

   Extract it in c:/php54/

   Note that you may also need to install the visual c++ redistributable
   environment (link from the PHP download page above) - if you try
   running the php.exe from the command line and get a 'side-by-side
   permission denied' message the missing c++ libraries are probably the reason.


3. Copy the c:/php54/php.ini-development config file to c:/windows/php.ini
   (the development one is best with an initial install, as it includes
    debugging info if any setting is wrong. For production, you can switch
    to the -production sample once the basics are working.)

   Edit the php.ini settings for FastCGI use:

fastcgi.impersonate = 1
fastcgi.logging = 0
cgi.fix_pathinfo=1
cgi.force_redirect=0


   Also increase the php.ini limits for use by annotate:

post_max_size = 80M
max_execution_time = 300
upload_max_filesize = 80M
date.timezone=Europe/London


4. Create a new user account to run annotate as:
   
  Start - Control panel - Add or remove user accounts

  Add a user called 'annotate' and set a password.


5. Create a folder to install annotate in:

  e.g. c:\annotate

  NB it is better to install annotate in a separate
  folder than under c:\inetpub, as that folder has 
  too many NTFS file system restrictions to run 
  the annotate pdf conversion utilities.


6. Create a 'test.php' php file in that folder
   containing: 
   <?php phpinfo(); ?>


7. Configure IIS to use FastCGI for *.php files in the annotate folder:

   Start the IIS manager (Start - search for 'iis' - IIS Manager)

   Select the server (YOUR-PC); 
     double-click "Handler Mappings"
     Add Module Mapping ...

   In the Add Module Mapping dialog, enter:
     Request path: *.php
     Module      : FastCgiModule
     Executable  : c:\php54\php-cgi.exe
     Name        : PHP vis FastCGI
   OK, then confirm creation of the fastcgi mapping.


8. Create the alias to your install folder:
   In IIS Manager, Right-click on Sites/Default Web Site
   Add virtual directory...
     Alias: annotate
     Physical path: c:\annotate



9. Switch the user account this application runs as:
   In IIS Manager, click on the Default Web Site/annotate folder.
   double-click on "Authentication" icon.
   Select "Anonymous Authentication", and the "Edit..." action
   Set the Anonymous user identity to be:
      Specific user: annotate    Set..
   using the the annotate user and password you created in step 4.


10. Check you can browse to: localhost/annotate/test.php 
   and see the php information summary.

Download the Annotate V4 server code

You can download the annotate server code for windows from the link below. A password is required to access the download; this will be supplied when you purchase a license

Installing annotate

You should extract the zip file into a top level folder like c:\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

Once you have PHP and IIS set up, steps to install annotate are:

1. extract the annotate .zip file into c:\annotate
2. run 'install.bat' from the command line to create the docs/ and private/ folders
3. copy 'php/phpconfig-windows.inc' to 'php/phpconfig.inc' and edit the settings (see below)
4. visit http://{yoursite.com}/annotate/index.php to create the admin account.

How to 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. An example is provided in phpconfig-windows.inc which you should copy to 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 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:/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;

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 generated on windows installations of the server.

Windows 7 configuration tips

A default windows 7 install will hide file extensions which can be confusing. You can shown them with Organize - Folder and search options - View tab - and uncheck: Hide extensions for known file types.

You can use Icacls in place of cacls to change permissions, or grant full control of Users to the annotate/ folder.

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. Viewing the site in Chrome browser and pressing F12 will show if any network requests are failing, which can be useful for diagnosing configuration problems.

Adding support for uploading DOC, DOCX, PPT 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 c:\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 Annotate 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.

Version history

The notes below summarise changes included with particular releases:

v4.2.6 [Jul 2016]
 - New release for Summer 2016 update to www.annotate.co service

v4.2.4 [Aug 2015]
 - New release for Summer 2015 update to www.annotate.co service

v4.1.8 [Oct 2014]
 - Initial release version for public www.annotate.co service

v4.0.28 [Oct 2012]
 - Initial beta release of V4

Please email any questions to support [at] nnotate.com.