https://github.com/dlcs/elucidate-server
A W3C and OA compliant Web Annotation server
https://github.com/dlcs/elucidate-server
annotations dlcs elucidate elucidate-server java json-ld oa open-annotation w3c w3c-annotations web-annotation web-annotation-protocol
Last synced: 16 days ago
JSON representation
A W3C and OA compliant Web Annotation server
- Host: GitHub
- URL: https://github.com/dlcs/elucidate-server
- Owner: dlcs
- License: mit
- Created: 2016-12-06T11:00:15.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2022-01-04T16:32:58.000Z (about 4 years ago)
- Last Synced: 2024-04-18T20:36:11.480Z (almost 2 years ago)
- Topics: annotations, dlcs, elucidate, elucidate-server, java, json-ld, oa, open-annotation, w3c, w3c-annotations, web-annotation, web-annotation-protocol
- Language: Java
- Homepage: https://dlcs.info/features.html
- Size: 577 KB
- Stars: 51
- Watchers: 20
- Forks: 15
- Open Issues: 24
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-iiif - Elucidate - Java and Postgres annotation server. (Annotations / Annotation Servers)
README
# Elucidate
Elucidate is a Web Annotation server that is compliant with both the [W3C Web Annotation Data Model](https://www.w3.org/TR/annotation-model/) and associated [protocol](https://www.w3.org/TR/annotation-protocol/), and the [Open Annotation (OA) Data Model](http://www.openannotation.org/spec/core/).
## Build Status
| Branch | Status |
|-----------|--------------------------------------------------------------------------------------------------------------------------------|
| `master` | [](https://travis-ci.org/dlcs/elucidate-server) |
| `develop` | [](https://travis-ci.org/dlcs/elucidate-server) |
## 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`](elucidate-parent/)
* Parent Maven project that defines dependency library version numbers and common dependencies amongst all Elucidate projects.
* [`elucidate-common-lib`](elucidate-common-lib/)
* Contains common classes that are used by similar projects.
* [`elucidate-converter`](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 | `` | Database user to authenticate as.
| db.url | `` | 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 | `` | 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`](elucidate-server/src/main/resources/elucidate-server.properties).
Any of these options can be configured or overridden using [JNDI environment properties](https://docs.oracle.com/javase/jndi/tutorial/beyond/env/source.html) 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](https://www.liquibase.org/) 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`](USAGE.md) for some sample requests.
## Built With
* [Spring Framework](https://projects.spring.io/spring-framework/)
* [Jackson](http://wiki.fasterxml.com/JacksonHome)
* [JSONLD-JAVA](https://github.com/jsonld-java/jsonld-java)
* [JSON Schema Validator](https://github.com/daveclayton/json-schema-validator)
* [Liquibase](https://www.liquibase.org)
## Contributing
Please read [`CONTRIBUTING.md`](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](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/dlcs/elucidate-server/tags).
## License
This project is licensed under the MIT License - see the [`LICENSE`](LICENSE) file for details