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 |
 |
develop |
 |
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