A W3C and OA compliant Web Annotation server
Clone or download

README.md

Elucidate

Elucidate is a Web Annotation server that is compliant with both the W3C Web Annotation Data Model and associated protocol, and the Open Annotation (OA) Data Model.

Build Status

Branch Status
master Build Status
develop Build Status

Getting Started

Prerequisites

Elucidate Server has been built and tested against:

Java 8+
Apache Tomcat 8+
PostgreSQL 9.4+

Elucidate Server and its dependencies are written in pure Java, and is designed to work with PostgreSQL by default.

Building

The Elucidate Server has a number of dependencies that must be built first:

  • elucidate-parent
    • Parent Maven project that defines dependency library version numbers and common dependencies amongst all Elucidate projects.
  • elucidate-common-lib
    • Contains common classes that are used by similar projects.
  • elucidate-converter
    • Simple library that (at present) allows for conversion between a W3C Web Annotation and OA Web Annotation.

Each dependency and the Elucidate Server itself can be built using Maven:

mvn clean package install -U

Configuration

Elucidate Server requires that several configuration properties are set to function correctly.

Name Default value Description
db.user <empty> Database user to authenticate as.
db.url <empty> JDBC database URL to connect to.
base.scheme "http" The URI scheme that annotation IRIs will use.
base.host "localhost" The hostname that annotation IRIs will use.
base.port 8080 The port that annotation IRIs will use. May be omitted if it set to a default HTTP/HTTPS port.
base.path "/annotation" The path prefix that that annotation IRIs will use.
log4j.config.location "classpath:logging/log4j.xml" A path to a log4j XML configuration/properties file.
auth.enabled false A flag indicating if authorization on annotation access should be enabled.
auth.token.verifierType secret Either secret or pubkey, indicating whether the JWT verification key is a shared secret or an RSA public key.
auth.token.verifierKey <empty> The secret or public key used to verify signed tokens.
auth.token.uidProperties sub,user_name The name of the JWT property that represents a unique user ID.

A full listing of configuration options available to change can be found in elucidate-server.properties. Any of these options can be configured or overridden using JNDI environment properties by passing a Java system property on the command line or setting an environment variable.

Note: if set as an environment variable, the option name should be uppercase with any hyphens and periods replaced with underscores. E.g., base.port becomes BASE_PORT.

Database

Elucidate Server has been built and tested against PostgreSQL 9.4+ (the jsonb type is required for persistence).

A Liquibase changelog contains the SQL scripts required to create the Elucidate Server schema. On first connection to a JDBC URI (given by db.url) the changes will be applied and a changelog table created in the database for any subsequent runs.

Security

Elucidate Server supports user authentication and authorization using detached JWTs as credentials. Authentication can be enabled or disabled by toggling the auth.enabled property listed above. Those tokens can be verified using either a shared secret key or RSA public key (given by auth.token.verifierType and auth.token.verifierKey).

Since Elucidate doesn't store authoritative user information on its own, it relies on the token providing a unique property that can be used to refer to that user throughout the lifetime of their interactions with the annotation server. A list of properties that will be searched for the unique value can be configured by setting the auth.token.uidProperties option.

Usage

See USAGE.md for some sample requests.

Built With

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Contributors should ensure that their code is formatted in a style that is as close to the existing style as possible.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

License

This project is licensed under the MIT License - see the LICENSE file for details