This server enables people to store and publish annotations on the web, as described in the Web Annotation Discovery proposal.
It has been developed and tested in combination with the Web Annotation Discovery WebExtension browser extension. Other clients that speak the Web Annotation Protocol should be compatible too (if, for writing to the server, they support HTTP Basic Authentication).
Minimum viable product, or primarily a proof-of-concept: This software demonstrates a mechanism for web annotation in practice, enabling people to try it out and hopefully move forward with the idea.
The software can be used for collaborative annotation, but be prepared for possible technical glitches (including data loss or leakage), mediocre user experience, and awful interface design.
Tested with NodeJS version 16 (LTS).
Clone this repository:
git clone …
Add a user (or several) in
Run the server:
Point your browser to your server (by default it’s
http://localhost:8080/), click your username and create a collection. Name it e.g. “My notes”. The browser should prompt you now for your username and password, which it remembers for subsequent requests. (Without any obvious way to log out, however..)
For the next steps, ensure you have the Web Annotation Discovery WebExtension installed and enabled in your browser.
Visit the collection’s URL, e.g.
http://localhost:8080/alice/my_notes/. The browser extension will discover the
<link> tag in the collection page, and offer to subscribe to this collection.
The browser extension will then display notes in the collection on pages you visit, and let you select this collection for any new annotations you make. See the documentation of the browser extension for more explanation on its usage.
When publicly accesible, always run this server behind a reverse proxy that only permits connection via TLS. Authentication is performed using the HTTP Basic Authentication, so passwords would otherwise be sent around the world in plaintext.
The list of known users and their passwords is configured in
config/users.json. The default is
alice with password
By default, data is stored in
/tmp/annotationdb; configure this in
Note that all annotations on the server are publicly readable. Only the owner of a collection can create/modify annotations in it. More granular control has not (yet) been implemented, but your reverse proxy could shield of a user’s whole path (i.e.
/username/*) or individual collections (
/username/collection_name/*) if desired.
Install dependencies using
npm install; then running
npm start should spin it up. Or
npm run dev runs it with live reloading upon source file changes.
For authentication (for
DELETE requests), HTTP Basic Authentication is used, as it is simple and (somewhat) supported by most web browsers.
Much of this code is derived from simple-annotation-server by Jan Kaßel, MIT-licensed.
Anything else in this repository is free and unencumbered software released into the public domain.
This project was funded through the NGI0 Discovery Fund, a fund established by NLnet with financial support from the European Commission’s Next Generation Internet programme.