W3C AnnoteaDocumentation

Annotation Server HOWTO for Debian Systems

Annotea project | server status | mailing list archive

This document is a description of how to set up and use a W3C-Perllib Annotations server on a Debian potato release but are likely to be usefull on other Debian releases and other Linux distributions. Please see the windows-specific or the general guide if you are installing on another system. The W3C annotation server is maintained on a debian potato distribution. The debian-specific is maintained in parallel with this server and is therefor the recommended system.

The W3C PerlLib Annotation Server consists of a set of perl libraries, CGI scripts and configuration files. These libraries have been tested with MySQL and Apache. Following are the instructions for installing PerlLib, MySQL, Apache, and configuring the libraries to work with them.

Overall Steps

  1. Install Perllib
  2. Install MySQL
  3. Set up RDF datastore with MySQL
  4. Install a Web Server
  5. Configure the Web Server
    1. Annotations Script
    2. Access Control
    3. Debugging Tools
  6. Try It!

1. Install Perllib

Check perlib out of CVS as follows. See the distribution guide for furthur details.

cd /usr/local
cvs -d :pserver:anonymous@dev.w3.org:/sources/public login
cvs -d :pserver:anonymous@dev.w3.org:/sources/public -z3 checkout -r V1_1 perl/modules

When prompted for a password for login, enter "anonymous".

2. Install MySQL

apt-get install libmysqlclient6
apt-get install mysql-client
apt-get install mysql-server

PerlLib uses the perl DBI database interface.

apt-get install libdbd-mysql-perl

3. Set up RDF datastore with MySQL

Perl code implements an RDF datastore that is installed on top of MySQL. The Annotations server is an additional narrow shim on top of the general RDF database. The annotate CGI script's SQL access parameters are configured with the Conf/rdf.prop properties file:

cat > /usr/local/perl/modules/Conf/rdf.prop
user: root
password: 
database: rdf
queryHost: localhost:3306

4. Get a Web Server

apt-get install apache-common
apt-get install apache
apt-get install apache-dev
apt-get install apache-doc

You may want to experiment with using mod-perl. We have installed this (see rough notes) but not tried it on a production system.

5.2. Access Control

You may wish to provide some authentication and trackability. To use Apache's basic authentication modules, uncomment the authentication-related directives in the Location "/access" directive (above).

You may wish to customize your own security policy, in which case you may wish to check out these notes on implementing authentication in a CGI script. There is a script to manipulate user access in W3C/Annotations/access. This is traditionally accessedvia the /access URL.

LoadModule dbm_auth_module /usr/lib/apache/1.3/mod_auth_dbm.so

ErrorDocument 401 /authRequired.html

ScriptAlias /access  /usr/local/perl/modules/W3C/Annotations/CGI/access
<Location "/access">
   AllowOverride None
   Options ExecCGI
   Allow from all
</Location>

Add the following line to ...Conf/annotate.prop and Annotations.access.prop:

auth.database.parms: -type=>'ndbm', -file=> /etc/apache/users

This file should correspond to the one indicated in <Location "/annotate">'s AuthDBMUserFile directive.

The authRequired.html page should have a pointer to /access if you wish to advertise a facility for unknown users to sign up to use the service. For instance, annotest has uses the ErrorDocument directive:

ErrorDocument 401 /authRequired.html

to point to an HTML document with a link to /access.

<p>You may request an account by completing and submitting the
  <a href="/access">access request form</a>.</p>

5.3. Algae Script

The algae CGI script is usefull for exploring the results of queries.

ScriptAlias /algae  /usr/local/perl/modules/W3C/Rdf/CGI/algae
<Location "/algae">
  AllowOverride None
  Options ExecCGI
  Allow from all
  AuthType Basic
  AuthName W3C_RDF
  AuthDBMUserFile users
  AuthDBMGroupFile groups
  <Limit GET PUT POST DELETE>
    Require group registered
  </Limit>
</Location>

6. Debugging Tools

Here are some handy idoms for checking/manipulating the users database with the perl debugger:

$ cd /etc/apache/conf/
$  perl -de 0
DB<1> use POSIX;

DB<2> use NDBM_File;

DB<3> tie(%users, 'NDBM_File', 'users', O_RDONLY, 0) || print "failure: $!"

DB<4> p join ("\n", keys %users)
joe@localhost
fred@expample.com
DB<5> p $users{'fred@expample.com'}
xxxxxxxx:2:0:3:yyyyyyyy:fred@expample.com:Smith:Fred:978120258:978120140
DB<6> untie(%users)

DB<7> tie(%users, 'NDBM_File', 'users', O_RDRW, 0) || print "failure: $!"

DB<8> %db{'joe@localhost'} = 'zzzzzzzz:2:0:3:aaaaaaaa:joe@localhost:Smith:John:978120258:978120140'

DB<9> untie(%users)

Property file example: *Note* this "documentation" will move shortly

The newUser script relies on a property file in Conf/newUser.prop for configuration:

email.from=webmaster@annotest.w3.org
html.navbar="<a href="http://www.w3.org/"><img src="http://www.w3.org/Icons/WWW/w3c_home" alt="W3C" class="W3CIcon" border="0" /></a><a href="/"><img src="/Icons/pen3.png" alt="Annotea" width="150" height="110" border="0" /></a>"

7. Try It!

You can use Amaya to test the annotations server. It also has an HTML interface so you can try creating annotations in RDF by pointing a normal browser at http://<server>/annotate.

Common Problems

OK, so that didn't work. You probably noticed this when you see something other than what you want showed up in your browser. This is useful information. So is the content of the error.log, which is in /var/log/apache/error.log in the standard setup.

I got a page of perl back.
Perhaps you don't have CGI enabled.
LoadModule cgi_module /usr/lib/apache/1.3/mod_cgi.so
Auth Required page not found.
You need to create /var/www/authRequired. You will probably want to put in some HTML with a link to /access if you want people to be able to make their own accounts.
Internal Server Error

Look in your error log. It probably says something like

Premature end of script headers: /usr/local/perl/modules/W3C/Annotations/CGI/access

This happens when the script has a problem and responds with an error message rather than the HTML headers and body that apache is expecting from it. Run the program in question

cd /usr/local/perl/modules/W3C/Annotations/CGI/
./access DEBUG

You will usually see something like

unable to open "/tmp/access.log": No such file or directory
W3C::Util::Exception thrown at ../../../W3C/Util/W3CDebugCGI.pm:488
W3C::Util::W3CDebugCGI::LoadSelf(...) at ../../../W3C/Util/W3CDebugCGI.pm:139
W3C::Util::W3CDebugCGI::loadOrSave(...) at ../../../W3C/Util/W3CDebugCGI.pm:107
W3C::Util::W3CDebugCGI::new(...) at ./access:70
(eval) at ./access:68
W3C::Annotations::CGI::Access::main(...) at ./access:64

which will give you a hint as to how to proceed.


Eric Prud'hommeaux,
@(#) $Id: RdfDB-debian.html,v 1.11 2002/08/02 18:09:04 eric Exp $ Valid HTML 4.0!