A.nnotate server installation guide
Part 2: optional modules

This document describes how to install the optional modules for A.nnotate, and should be read after completing the basic install (with PDF and HTML support). Note that installing these modules is more complex than installing the basic A.nnotate server. You can install all, none or just a subset of these modules, depending on your requirements.

• 1. Enabling the Apache user to run programs
• 2. OpenOffice suppport - so you can upload Word / Powerpoint / Excel documents
• 3. File upload progress meter - this requires a Perl utility to be installed in cgi-bin
• 4. Generating thumbnails of snapshotted websites

1. Enabling the apache user to run programs

Typically PHP scripts are run as the apache user - which is a restricted account with no home directory. On Ubuntu linux, the default apache user is set up as www-data; one way to find our which user apache runs as on your system is to type ps aux | grep httpd and see who owns the cluster of 'httpd' processes.

If you want to be able to run openoffice or firefox as the apache user, (to support uploading Word documents and generating thumbnails of web pages) you will need to create a home directory where these applications store their profile settings.

   # As root: first check if the apache user
   # already has a home directory that it can write to:
   #   N.B. if apache runs as a different user
   #   e.g. 'www-data' you should replace 'apache' with 'www-data'
   #   throughout this guide, e.g.
   #     su www-data
   #   
   % su apache
   $ cd
   $ touch tmp.tmp

   # If this works, and the apache home directory is writable by
   # the apache user, you can skip the rest of this section.
   # If this fails, you need to set up a home directory
   # for the apache user - the example below sets it
   # to '/var/www/ahome':-

   % cd /var/www
   % mkdir ahome
   % chown apache ahome
   % chgrp apache ahome

   # Enable home directory for apache:
   % vi /etc/passwd

   # edit the entry for the apache user to allow logins
   # and set the home dir, e.g.:
   apache:x:48:48:Apache:/var/www/ahome:/bin/bash

   # Check you can su to the apache user now:
   % su apache

At this point you should also change the settings in the configuration file in annotate/oo/bashconf.tmp, which is included by the various scripts for running openoffice and firefox:

  % su annotate
  $ cd /var/www/html/annotate/oo
  $ vi bashconf.tmp

  # as the annotate user, edit the settings in annotate/oo/bashconf.tmp:

  APACHE_USER=apache
  APACHE_HOME=/var/www/ahome

2. Adding OpenOffice support

Install openoffice 2.4.1 or later : www.openoffice.org. It will install itself to somewhere like /opt/openoffice.org2.4/program. Earlier versions had to be run with an X framebuffer, so it is worth upgrading to 2.4+ (which can be run in server mode) even if you have an old version already.

Many linux distributions only offer older versions of openoffice via their standard install mechanism, so it is worth downloading directly from the openoffice site. To fetch the openoffice 2.4.1. binary directly onto the server, you can follow the steps below:-

   # Check you can run openoffice as a normal user:
   % su annotate
   $ vi .bashrc
   export PATH=/opt/openoffice.org2.4/program:$PATH
   $ source .bashrc

   # On your local machine, set xhost+ and check your firewall
   # can accept X connections on the normal TCP port (6000)
   $ export DISPLAY={your ip}:0.0
   $ soffice &

   # on Ubuntu, the executable could be called 'ooffice' not 'soffice'
  

There is a test document in annotate/oo which you can try, but first you need to check the settings in annotate/oo/bashconf.tmp:

  # As the annotate user, check the paths in the config file: oo/bashconf.tmp:
  % su annotate
  $ cd /var/www/html/annotate/oo          # ... where you installed annotate
  $ vi bashconf.tmp
  OOPATH=/opt/openoffice/2.4/program
  OOEXE=/opt/openoffice/2.4/program/soffice
  OOEXENAME=soffice.bin
  OOPYTHON=/opt/openoffice/2.4/program/python.sh

  # If any of these are not correct, edit the bashconf.tmp file.
  # The OOPYTHON setting points to the version of python which is
  # bundled with the installation of openoffice from openoffice.org.
  # For Ubuntu, you can change this to your standard python install
  #  (e.g. /usr/bin/python).  You will need the python-uno package  
  #  installed for calling openoffice.


  # The following command should convert 'test.odt' to '/tmp/test.pdf'
  $ ./ooconv.sh test.odt /tmp/test.pdf

You can check whether you can run the conversion as the apache user (complete the steps above 'enabling the apache user to run programs').

  # ... login as root
  % su apache

  $ cd /var/www/html/annotate/oo   # ... or your install directory
  $ ./ooconv.sh test.odt /tmp/test2.pdf

  # If you get something like ERROR! ErrorCodeIOException 525
  # check that the output PDF file is writable by the current user

Running openoffice in server mode

The test conversion above started openoffice, converted a document, then killed the openoffice process. This can take a few seconds for each document. You can avoid the openoffice startup time by running it in server mode, listening to a socket for incoming documents. This also has the advantage that you can run openoffice as a separate user from the Apache one (e.g. you could create a new user just to run openoffice).

  # As the user you want to run openoffice as:
  # (as root)
  % adduser openoffice

  % su openoffice

  # (as the 'openoffice' user')
  $ cd /var/www/html/annotate/oo
  $ ./oocron.sh                 # this starts up openoffice

  # Check that the 'soffice.bin' process is running:
  $ ps aux | grep soffice

  # Try converting a test file again a couple of times, running
  # as the apache user:
  # (as root)
  % su apache

  $ ./ooconv.sh test.odt /tmp/test5.pdf
  $ ./ooconv.sh test.odt /tmp/test6.pdf

  # All being well, the second time should have been much
  # faster, as you avoid the startup time of openoffice.

  # You need to keep the openoffice process alive all the time
  # e.g. using a cron job, as your chosen openoffice user, adding an
  # entry like:
  # as root...
  % su openoffice
  $ crontab -e
* * * * * bash /var/www/html/annotate/oo/oocron.sh >/dev/null 2>&1

While openoffice is running in server mode, the conversions from office formats should be much faster.

Updating the php/config.tmp file to enable openoffice support

To enable support for the office formats when you upload a document to your annotate server, edit your php/config.tmp file as follows:

  # Edit the setting in php/config.tmp to point to the ooconv.sh script:
  % su annotate
  $ cd /var/www/html/annotate/php        # ... or your install directory
  $ vi config.tmp
  $ooshcommand="/bin/bash /var/www/html/annotate/oo/ooconv.sh";

  # Test it out by uploading a short Word / openoffice file on your
  # documents.php page.

3. File upload progress meter

To display a progress bar during upload, you need to install a Perl script into the cgi-bin directory.

  # If you haven't yet set up your server to run cgi-bin scripts yet:
  #   As root, check the Apache configuration file
  #   (e.g. in /etc/httpd/conf or /etc/apache2/apache2.conf /mnt/install/apache/conf/httpd.conf)
  #   If you haven't set up your apache for cgi-bin, check
  #   that the mod_alias module is installed.
  %   vi /etc/httpd/conf
  #   The cgi-bin setting will be in a line like:-
  ScriptAlias /cgi-bin/ "/var/www/cgi-bin/"

  # You can put the Annotate perl scripts in a subdirectory:
  # as root:
  % mkdir /var/www/cgi-bin/annotate
  % chmod a+rx annotate
  % cd /var/www/cgi-bin/annotate
  % cp /var/www/html/annotate/cgi-bin/* .

  # The settings are in a perl file 'fheader.tmp' - edit this
  # to make sure the paths are set correctly. The important
  # setting here is the temporary directory to use for uploads,
  # as it must agree with the setting in php/config.tmp
  # You can leave it as the default (/tmp/annotate), or change
  # it in both places.

  % vi fheader.tmp
  $tmp_dir="/tmp/annotate";

  % chmod a+x *

  # Test running the perl script from the command line.
  # If you get any error messages here, the script won't
  # run from the cgi-bin directory either.

  % ./fheader.tmp
  # ... this should do nothing.

  # Try visiting:  http://your.server/cgi-bin/annotate/printenv.pl from browser
  # to check the cgi-bin is working. It should print out a list of environment
  # variables to the browser.

  # Gotchas: if you get 'Internal Server Error' it could be
  # caused by having DOS not Unix return characters at the end of
  # the script lines.  You can fix this with the dos2unix command.
  # Also worth checking the log files (somewhere like /var/log/httpd)
  # Some perl / cgi-bin installations have security settings which 
  # will only run cgi-bin programs if they have the same owner/group
  # as the cgi-bin user, so you may need to set the owner of the cgi-bin
  # perl scripts if this is the case.

  # Edit the php/config.tmp file to switch the file upload progress bar on:
  % su annotate
  $ cd /var/www/html/annotate/php
  $ vi config.tmp

  $uploadtmpdir = "/tmp/annotate";

  $fileuploadprogress = true;
  $fileuploadcgibin = "/cgi-bin/annotate/";


  # Try uploading a pdf file by browsing to your documents.php page;
  # you should now see a blue progress bar during the upload.

4. Generating thumbnails of websites

To generate thumbnails of websites (displayed on your index pages next to the list of notes), you need to install a web browser (firefox) and a virtual X framebuffer (Xvfb). You will also need the netpbm tools (pnmtopng, pnmscale).

   # As root:
   # (on fedora core 4):-
     % yum install xorg-x11
     % yum install xorg-x11-Xvfb

   # (on fedora 8):-
     % yum install xorg-x11-server-Xorg
     % yum install xorg-x11-server-Xvfb
     % yum install xorg-x11-fonts-*

   % yum install firefox

The thumbnail generation will be run as the apache user on some systems. However, in order to enable the apache user to run firefox, there has to be a home directory created for apache (on many systems, apache runs as a restricted user). (see section 1 above for creating a home directory for apache).

   # Check you can su to the apache user:
   #   (on Ubuntu, this is 'www-data' not 'apache'):
   #    su www-data
   % su apache

   # Try running firefox as the apache user; store
   # the settings in the profile 'test'
   # On your local machine, xhost+
   $ export DISPLAY={your IP}:0.0
   $ firefox -CreateProfile test

   # Run firefox with the display on your X window:
   $ firefox -P test http://www.textensor.com

   # Resize the window to be about 1000 x 1024 pixels.
   # When firefox starts again, it will keep
   # the size, which will be used for the screenshots
   # for the thumbnails.

   # At this point, you also need to switch off the
   # 'Restore session' window which will appear on
   # restarting firefox if it crashes for any reason.
   # 1. Type 'about:config' in the location bar.
   # 2. go to the 'browser.sessionstore.enabled' setting
   # 3. change the setting to false (double-click on the entry)

   # Quit firefox, and the settings will be saved in the profile.

To run firefox on the server, you will need to have the Xvfb frame buffer running all the time. One way to do this is to set up a cron job to check Xvfb and start it if it is not running - this will also automatically restart the X display if the process dies for any reason.

   # As root...
   % su annotate
   # We will run the X framebuffer as the 'annotate' user.

   # Check that you can start Xvfb manually:
   $ cd /var/www/html/annotate/php/
   $ ./startxvfb.sh

   # If this works ok, check you can run firefox using the Xvfb display:

   $ export DISPLAY=:1
   $ firefox &

   # You won't see any output, as firefox is displaying to 
   # the Xvfb virtual frame buffer.
   # Kill the firefox process if you get no error messages.
   # You can use 'jobs' to find the process number, e.g.:
   $ kill %1


   # To ensure the framebuffer is always running all the time, you
   # can add a CRON job.

   $ export DISPLAY={your ip}:0.0

   # Edit the cron list for the 'annotate' user.
   $ crontab -e

   # Add a line like (with the correct path to startxvfb.sh)
   * * * * * bash /var/www/html/annotate/php/startxvfb.sh >/dev/null 2>&1

   # You can check the XVfb process is running after a minute using 'top'
   # It will create a X server on localhost:1.0

To test it out, you can take a snapshot of a web page, and look at its index page - it should show 'Generating thumbnail...' and then a small image. The image is stored somewhere like: /var/www/html/annotate/docs/{date}/{code}/small.png

If the thumbnail is not generated correctly, you can also try running the thumbnail generator from the command line :

   # as root...
   % su apache        # or your apache user, e.g. www-data on Ubuntu
   $ cd /var/www/html/annotate/php/
   $ ./fpreview.sh http://www.textensor.com
   # ... should generate a thumbnail '/tmp/small.png'
   # if it doesn't work, check the paths in the oo/bashconf.tmp settings
   # in particular APACHE_HOME, APACHE_USER, FIREFOXEXENAME and FIREFOXEXE

Questions / problems:

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