unilenlac/stemmaweb repository overview

⁠Stemmaweb - a Catalyst web interface for text tradition analysis

Stemmaweb is a web interface for analyzing variations between different manuscript versions of the same text. The interface also allows to import traditions and export critical text editions. It is built using the Catalyst framework in Perl and utilizes JQuery for the frontend.

This version of Stemmaweb is a fork of the original project, with additional features and improvements.

This fork is maintained by the IRSB⁠ (Institut Romand des Sciences Bibliques) of the University of Lausanne⁠.

⁠The Stemmaweb environment

Originally the Stemmaweb frontend has been built to work with the Stemmarest⁠ backend, which provides a RESTful API for accessing and manipulating text traditions.

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.

⁠Installation & Quick Start

This web interface uses the Perl⁠ language and the Catalyst framework⁠.

Because Perl/Catalyst can be challenging to configure locally, we highly recommend running Stemmaweb inside a Docker container.

⁠Option 1: Run with Docker (Recommended)

Stemmaweb is containerized and ready to deploy.

1. Build the image:

   docker build -t stemmaweb:ubuntu-18.04 .
   

   Copy

2. Run the container (requires passing the SBRIDGE_URL environment variable parameter):

   docker run -e SBRIDGE_URL="http://your-sbridge-host:sbridge_port" -p 3000:3000 stemmaweb:ubuntu-18.04
   

   Copy

Optional: Run for local development (mounts your current directory for hot reloading when files change):

docker run -it --rm \
  -p 3000:3000 \
  -v $PWD:/stemmaweb \
  -e SBRIDGE_URL="http://your-sbridge-host:sbridge_port" \
  stemmaweb:ubuntu-18.04 \
  perl script/stemmaweb_server.pl -r

1. Production Deployment: You can configure Stemmaweb to run under FastCGI, Starman, or any other Catalyst-compatible application framework (see the Catalyst documentation). The provided stemmaweb.psgi is configured to run behind Apache on a specified non-root URL path.

Debugging screen is then available, for instance, if the container is running is not running on the background:

docker run -it --rm --name stemmaweb --network stemmaweb -p 3000:3000 stemmaweb:ubuntu-18.04

⁠Configuration

Stemmaweb needs to be configured to connect to the Stemmarest backend. This typically involves setting the API endpoint URL.

The API endpoint can be set in the Stemmaweb configuration file (e.g., stemmaweb.conf) under the [tradition_repo] variable:

<Model Directory>
	tradition_repo http://my-server:8080/stemmarest/api
</Model Directory>

Stemmaweb also needs to be configured to connect to the s-bridge module. This involves setting the API endpoint URL in the Stemmaweb configuration file stemmaweb.conf:

You must use the __ENV(VAR_NAME)__ macro to load values from environment variables at runtime, which is useful when deploying the Docker container:

<Component Controller::Sbridge>
    sbridge_url __ENV(SBRIDGE_URL)__
</Component>

⁠Usage guide

A small usage guide can be found in the interface. In this section we show very briefly how to use the exporation feature :

After having finished your critical edition, exportation can be done by :

• Go to the home page and sign-in.
• Select the tradition you need to export on the left selection panel.
• Click the "Download tradition" button on the right side of the interface.
• Select the XML exportation format.
• Select the section range you want to export.
• Click the "Download" button to download the file.

Exportation errors are displayed in the download window. A more detailed error log can be be downloaded if a link is provided with the error message.

You can also export the critical text of a section.

• select a tradition with the 'view collation and edit relationships' button.
• select a section eventually.
• find the "Download section" button on the top part of the interface.
• Select the XML exportation format.
• When the document is ready, the XML file will be available for download.

Please note that the downloaded files are XML files that conform to the TEI (Text Encoding Initiative) guidelines.