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.
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
".
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
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
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.
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>
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>
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>"
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.
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.
LoadModule cgi_module /usr/lib/apache/1.3/mod_cgi.so
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.