First version published 2003-01-16. This is a preliminary draft missing critical content and including mistakes. $Id: Overview.html,v 1.5 2002/12/17 14:57:37 charles Exp $. This docment is expected to be updated during the life of the SWAD-Europe project to reflect or link to further developments in this area.
Comments on this document are welcome and should be sent to Charles McCathieNevile <charles@w3.org> General discussion of annotation systems and in particular Annotea should be sent to the W3C Annotation list www-annotation@w3.org - archives at http://lists.w3.org/Archives/Public/www-annotation/ allow you to search for old discussion of the server as well as other servers and systems. Comments on ZAnnot should be sent to the author of the software, Brent Hendricks <brentmh@rice.edu> (you may also like to copy the archived mailing list).
This document describes how to install the ZAnnot Annotea server, which runs as an extension to the Zope application server. People who simply want a working Annotea server should start at section 2 Installing the Software.
The ZAnnot server is written by Brent Hendricks, available under the GPL open source license. It is one of several Annotea servers available. It was chosen as the subject of detailed instructions because it is relatively simple to install. Information about other Anntoea servers [IMPLEMENTATIONS], and about clients that can be used with them is maintained by the Annotea project at W3C [ANNOTEA].
The Zope application server is an Open-source Web server written in Python. It is available for any system which runs python 2.1. Instructions are currently provided here for
The easiest way to install in OS X is via the fink packaging system. Fink is an open source system designed to provide easy acccess to Unix software on Mac OS X, and manage things like dependencies on Libraries.
To install fink, download the application and follow the instructions on the installation page. These are available from the fink project.
Please Note: This step will only be needed until the system has been better tested. Expert users will understand when this can be ignored or changed. Following the instructions given here should not cause any problem even when it becomes unnecesary. We recommend you check this page to see if the step is still recommended when you are ready to install ZAnnot.
To install Zope and ZAnnot, you need to move some package information from the "unstable" list to the "local" list, using an administrator's password. In a terminal window type
sudo cp /sw/fink/dists/unstable/main/finkinfo/web/zope* /sw/fink/dists/local/main/finkinfo
sudo cp /sw/fink/dists/unstable/main/finkinfo/web/zannot* /sw/fink/dists/local/main/finkinfo
sudo fink index
(and give your administrator password when asked).
In a terminal, type
fink install zannot
It may tell you that it is going to install some other software, such as python, that Zope needs to run. Press Return/Enter to agree, and it will then download the various packages and compile them. This takes some time, and produces a lot of messages. Eventually you will be asked for a username and password for the administrator of the Zope server. You should choose something you will remember. You will then be offered a choice of encryption systems, and should choose crypt if not sure, and asked for domain restrictions (where an administrator can connect from) - in in doubt choose localhost (the computer the server is installed on).
Username:dummy
Password:
Verify password:
Please choose a format from:
SHA - SHA-1 hashed password
CRYPT - UNIX-style crypt password
CLEARTEXT - no protection.
Encoding:crypt
Domain restrictions: localhost
The Zope project provides linux, solaris and windows binaries which include the python interpreter. Get the current Zope stable release and install it.
If you are using Debian linux you can install it via apt-get, with the following sequence of commands:
apt-get install python2.1-xml apt-get install zope
Install the ZAnnot package by unpacking it in the Zope Products directory. Wherever you installed Zope, there will be a directory lib/python/Products inside it (e.g. for a typical Windows installation this means Program Files / Website / lib / python / Products is the folder you should select to extract the files into.)
In unix you can do it as follows:
cd /usr/lib/zope/lib/python/Products wget http://www.zope.org/Members/Crouton/ZAnnot/ZAnnot-0.3.tgz tar -zxvf ZAnnot-0.3.tgz
(This assumes you put zope into /usr/lib, or used apt-get which does that for you automatically)
You need the source from Zope, plus Python 2.1. The Zope project includes instructions for installing Zope from source.
Then follow step 2: install zannot as for Windows or Unix, described above.
The Zope server must be restarted (or started for the first time) after the ZAnnot package has been installed. In a Unix system including Mac OS X type
sudo zopectl start
In Windows you need to run the start application in the Zope folder (Progam Files / Website in a default Windows install)
You can then administer the server through a Web browser, by going to the address http://localhost:8080/manage (http://localhost:9673/manage if you installed Zope in Debian using apt-get).
--what I would like to do here is clean my installation, go through the process step by step and at each step grab the source, so I can create a walk-through in HTML. This way people will find out what it looks like in their browser, even if that is emacs-w3 running through emacspeak or Amaya. (I did it on another machine, and also took screenshots. So it should become clearer soon...)
Steps
And that's it! There is now an Annotea server running at http://localhost:8080/zeno
From the security tab for the Annotations tab it is possible to control who can post or view annotations for a particular Annotation server. It is also possible to restrict access to a particular annotation, by eslecting that item in the directory that represents the annotation server, and specifying access controls for it.
The default is that items inherit security access from their parent objects - in other words annotations will each have the same access control as defined for the annotation server.
By adding several annotation server objects with different id's it is possible to run several annontea servers on the same system - each will have a different URI and seperate properties including access control rules.
For further information on access control and more detailed configuration options consult the help documentation supplied with Zope (it is possible to add a tutorial object so the zope server provides online help).
General questions about Annotea servers can be found in the SWAD-E Report RDF-based annotation systems (FAQs).
This work builds on the Annotea Project, which is partially funded by DARPA. This documentation describes the ZAnnot tool, developed by Brent Hendricks to provide an Annotea server which is easy to install and run, and which in turn depends on the Zope application server. This HOW-TO was produced as part of the SWAD-Europe project, funded by the European Commission.
The author thanks all the funders, the people responsible for the development of the protocols and systems, and in particular Brent Hendricks and Marja-Riitta Koivunen. Thanks also to Dan Brickley for road-testing and help on Debian, and to Ben Hines for help with fink packaging.