SWAD-Europe: Installing ZAnnot

Charles McCathieNevile, W3C
This document explains how to install the ZAnnot extension which provides a simple Annotea server for the Zope application server. It is an appendix to the SWAD-E report RDF-based annotation systems. ZAnnot is written by Brent Hendricks, and made available as part of the Zope project.

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).


  1. Introduction
  2. Installing the Software
  3. Configuring the Server
  4. Security, Licensing
  5. Frequently Asked Questions (FAQs)
  6. References
  7. Acknowledgements

1 Introduction

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].

2 Installing the Software

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

Mac OS X

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.

step 1: install fink

To install fink, download the application and follow the instructions on the installation page. These are available from the fink project.

step 2: setup fink to install ZAnnot

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).

step 3: install ZAnnot (and if required zope, python, etc).

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).


Verify password:

Please choose a format from:

SHA - SHA-1 hashed password
CRYPT - UNIX-style crypt password
CLEARTEXT - no protection.


Domain restrictions: localhost

Windows or Unix systems

Step 1: install Zope

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

Step 2: install ZAnnot

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)

Installing from source

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.

3 Configure the Server

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...)


  1. Add a user who is a manager (This step is only required on Unix / Mac OS X)
  2. Log in as the manager. On Windows this is the super-user you created as part of the install.
  3. Add an annotation server object, using the menu on the top right of the page. @@screenshot
  4. When asked for an Id and title, provide a one-word id (this will become the last component of the URI for the service - these instructions assume you use "zanno")
  5. Configure permissions for tha
    1. Select the zanno object in the main frame of the manager interface (it is in the list of objects). @@screenshot
    2. Select the security tab from the tabs across the top of the main frame.
    3. To allow open access, select the checkboxes immediately after (i.e. in the column "anonymous") the following options (screenshots)
      • Access contents information
      • View
      • ZAnnot add annotation
      • ZAnnot delete annotation
      • ZAnnot edit annotation

And that's it! There is now an Annotea server running at http://localhost:8080/zeno

4 Security and access control

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).

9 Frequently Asked Questions (FAQ)

General questions about Annotea servers can be found in the SWAD-E Report RDF-based annotation systems (FAQs).

Why can't I retrieve my annotations from a Windows server?
I don't know. This is my own question and I haven't found an answer. (Everything else seems to work as advertised).
Why is there no page at http://localhost:8080/ZAnnot
The ZAnnot server only provides an Annotea service that accepts new annotations or queries according to the protocol [PROTOCOL]. The W3C Annotea server provides an HTML form-based interface that can be used interactively.
Do I have to pay for the server? Can I sell a modified version of it?
The ZAnnot server is covered by the GPL license. This means it is open source - you can modify it, and even sell you modified version, but you must always make the source of your modified version freely available. The W3C Annotea server is available under the less restrictive W3C software license. (Both these servers are available for free).
Where do I find support, or send bug reports?


Annotation tools, specifications and documents

The Annotea protocol is documented at http://www.w3.org/2001/Annotea/User/Protocol
The www-annotation@w3.org mailing list is a public discussion forum for annotation systems, including Annotea. Its archives (including instructions for subscribing) are available at http://lists.w3.org/Archives/Public/www-annotation/


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.