unilenlac/stemmarest repository overview

⁠Stemmarest

⁠Stemmarest - a REST API for variant text traditions

Stemmarest is a Neo4j⁠-based repository for variant text traditions (i.e. texts that have been transmitted in multiple manuscripts). The repository is accessed via a REST API

This repository is a fork of the Stemmarest⁠ repository, that features critical edition exportation capabilities in XML format.

⁠Documentation

The original API documentation can be found here⁠.

As the code has been upgraded, a few routes have been added or modified. Please refer to the swagger generated documentation for the latest information. This documentation is available when the backend is running at the /stemmarest/api/docs endpoint.

⁠The Stemmaweb environment

Originally the Stemmarest backend has been built to work with the Stemmaweb platform, which provides a web-based interface for exploring and editing these traditions.

The Stemmaweb codebase has been adapted to work with this API. The fork can be found here⁠.

If you need a script to collate texts and import them into the stemmarest backend, you can use this collate and import script⁠. Please note that this script handles only XML texts that follows the ENLAC DTD⁠ specification, but can be modified to suit your needs.

⁠Upgrades and features

This version includes the following upgrades and new features :

• XML exportation : support for exporting a critical edition in XML format. Exportation result includes the critical text and the critical apparatus.
• Route : /tradition/complex added to retrieve/manage complex variant texts or hypernode (groups of nodes)
• code base upgrading to fit the latest version of Neo4j
• Improved database session initialization and configuration
• Improved database session management through the application
• OpenAPI documentation generation for all endpoints available at the /stemmarest/api/docs endpoint

⁠Docker

You can get a version of Stemmarest via Docker Hub:

docker pull unilenlac/stemmarest:1.2-tomcat9-jdk17

Then you can run a basic version of the container with:

docker run -it --rm --name stemmarest --network stemmaweb -p 8080:8080 unilenlac/stemmarest:1.2-tomcat9-jdk17

Debugging while the container is running is possible by opening a port and running a debugging server over the application. You also must use the JAVA_TOOL_OPTIONS environment variable to configure the debugger.

docker run -itd --rm --name stemmarest --network stemmaweb -p 8080:8080 -p 5005:5005 -e JAVA_TOOL_OPTIONS="-agentlib:jdwp=transport=dt_socket,address=*:5005,server=y,suspend=n"

⁠neo4j plugins and configuration

Two plugins are also provided in the plugins folder : APOC and Graph Data Science library. Default versions are :

• APOC version 5.22.0
• Graph Data Science version 2.8.0

Versions can be changed by using the following environment variables when building the docker image :

• APOC_VERSION
• GDS_VERSION Example :

docker build --build-arg APOC_VERSION=5.22.0 --build-arg GDS_VERSION=2.8.0 -t unilenlac/stemmarest:tag .

A default configuration file for the embedded version of Neo4j is also provided in the /var/lib/stemmarest/conf folder. You can change it by mounting your own configuration file in the same folder.

⁠Database

Neo4j embedded database stores his data and config files in the following directories:

• Data: /var/lib/stemmarest/data
• Config (neo4j): /var/lib/stemmarest/conf
• Plugin (neo4j): /var/lib/stemmarest/plugins

These folders can be used to mount volumes and persist data.

This API use the version 5.26 [LTS] of Neo4j for Java (embedded version⁠).

⁠Building

Stemmarest needs to be built using Maven⁠. This can be done either in a suitable Java IDE, or at the command line after the Maven tools have been installed:

mvn clean && mvn package -Dmaven.test.skip.exec=true

Please note, that this command will skip the tests as they are not fully upgraded on this version.

Make sure, that the package graphviz is installed on your computer. If not, some tests will fail.

A WAR file will be produced, in target/stemmarest.war, that can then be deployed to the Tomcat server of your choice.

⁠Deployment

This version runs on Tomcat version 9 with JDK 17; to deploy it, copy the WAR file into the webapps directory of your Tomcat server.

Stemmarest requires a location for its data storage; by default this is /var/lib/stemmarest, but can be changed by setting the environment variable STEMMAREST_HOME. The directory specified must have its permissions set so that the Tomcat user can write to it.

Note that if, at any time, you wish to inspect the database visually, you may shut down the Stemmarest server and start an instance of Neo4J at the database directory location. Make sure that your version of Neo4J matches the version specified in pom.xml!

⁠Todo

• Fix remaining tests that haven't been updated: the code is actually compiled without tests.
• Refactor code hierarchy: this code needs Separation of Concerns to be properly organized. Part of the code mainly concerned => Route logic, business logic, and data access logic should be separated.

⁠Background

Development of Stemmarest was begun by a team of software engineering students at the University of Bern⁠, and since 2016 has been continued by the Digital Humanities group at the University of Vienna⁠ with financial support from the Swiss National Science Foundation⁠.

This fork is an extension of the original Stemmarest project, incorporating updates and improvements to include lacking exportation features. This version is still under development by the Faculty of Theology and Religion⁠ at the university of Lausanne.

⁠License

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

⁠Contact

For any questions or issues, please open an issue on the GitHub repository or contact the maintainer at [[email protected]⁠]

Feel free to contribute to the project by submitting pull requests !