MEIGarage

Table of Contents

• About the Project
• How to use
• Installation
  • With Docker
  • Without Docker
• Building with Maven

About

MEIGarage is a webservice and RESTful service to transform, convert and validate various formats, focussing on the MEI format. MEIGarage is based on the proven OxGarage.

Further information on the code structure of MEIGarage and TEIGarage can be found here. Information in form of presentation slides and posters can be found here.

A running instance of MEIGarage can be found at meigarage.edirom.de.

How to use

Open API documentation can be found at https://github.com/Edirom/MEIGarage/blob/main/src/main/webapp/openapi.json or at the running instance https://meigarage.edirom.de/ege-webservice/. A curl example call to the API to convert an existing MEI 3.0 document to an MEI 4.0 document looks like

curl -o 4.0.0.mei -F upload=@input-3.0.0.mei https://meigarage.edirom.de/ege-webservice/Conversions/mei30%3Atext%3Axml/mei40%3Atext%3Axml/

Installation

Installing with Docker

With Docker installed, a readymade image can be fetched from the GitHub Docker Registry or DockerHub. For the frontend see ViFE mMeigarage Webclient.

docker pull ghcr.io/edirom/meigarage:latest or docker pull edirom/meigarage:latest

A container can be run using:

bash docker run --rm \ -p 8080:8080 \ --name meigarage edirom/meigarage:latest

Once it's running, you can point your browser at http://localhost:8080/ege-webservice for the webservice.

You can also get the development version from DockerHub with docker pull edirom/meigarage:dev.

available parameters

• -v Stylesheet paths : The local path to the stylesheets and sources can be mounted to /usr/share/xml/tei/ using the --volume parameter, using e.g. -v /your/path/to/Stylesheets:/usr/share/xml/tei/stylesheet \ -v /your/path/to/TEI/P5:/usr/share/xml/tei/odd

TEI and MEI sources and stylesheets

When the docker image is build, the latest releases of the TEI and MEI Sources and Stylesheets are added to the image.

If you want to use another version of the sources or stylesheets, you can mount the local folders where your custom files are located when running the Docker image.

There are several ways to obtain these (see "Get and install a local copy" at http://www.tei-c.org/Guidelines/P5/), one of them is to download the latest release of both TEI and Stylesheets from GitHub. Then, the Stylesheets' root directory (i.e. which holds the profiles directory) must be mapped to /usr/share/xml/tei/stylesheet whereas for the P5 sources you'll need to find the subdirectory which holds the file p5subset.xml and map this to /usr/share/xml/tei/odd; (should be xml/tei/odd).

The respective git repositories:

| location in docker image | data located there | | --------------- | --------------- | | /usr/share/xml/tei/stylesheet | https://github.com/TEIC/Stylesheets/releases/latest | | /usr/share/xml/tei/odd | https://github.com/TEIC/TEI/releases/latest | | /usr/share/xml/mei/music-stylesheets/encoding-tools | https://github.com/music-encoding/encoding-tools/releases/latest | | /usr/share/xml/mei/music-stylesheets/w3c-musicxml | https://github.com/w3c/musicxml/releases/latest | | /usr/share/xml/mei/music-stylesheets/meiler | https://github.com/rettinghaus/MEILER/releases/latest | | /usr/share/xml/mei/music-encoding | https://github.com/music-encoding/music-encoding - each released version sorted into the respctive folder | | /usr/share/xml/mei/music-stylesheets/data-configuration | https://github.com/Edirom/data-configuration - the whole repository|

Using your local folders for the TEI sources and stylesheets:

bash docker run --rm \ -p 8080:8080 \ -e WEBSERVICE_URL=http://localhost:8080/ege-webservice/ \ -v /your/path/to/tei/stylesheet:/usr/share/xml/tei/stylesheet \ -v /your/path/to/tei/odd:/usr/share/xml/tei/odd \ -v /your/path/to/mei/music-stylesheets/encoding-tools:/usr/share/xml/mei/music-stylesheets/encoding-tools \ -v /your/path/to/mei/music-stylesheets/w3c-musicxml:/usr/share/xml/mei/music-stylesheets/w3c-musicxml \ -v /your/path/to/mei/music-stylesheets/meiler:/usr/share/xml/mei/music-stylesheets/meiler \ -v /your/path/to/mei/music-encoding:/usr/share/xml/mei/music-encoding \ -v /your/path/to/mei/music-stylesheets/data-configuration:/usr/share/xml/mei/music-stylesheets/data-configuration \ --name meigarage ghcr.io/edirom/meigarage

You can also change the version that is used by supplying different version number when building the image locally running something like

bash docker build \ --build-arg VERSION_STYLESHEET=7.52.0 \ --build-arg VERSION_ODD=4.3.0 \ --build-arg VERSION_ENCODING_TOOLS=3.0.0 \ --build-arg VERSION_W3C_MUSICXML=4.0 \ --build-arg VERSION_MEILER=2.0.0 \ .

in your local copy of the MEIGarage.

exposed ports

The Docker image exposes two ports, 8080 and 8081. If you're running MEIGarage over plain old HTTP, use the 8080 connector. For HTTPS connections behind a SSL terminating Load Balancer, please use the 8081 connector.

Installing without Docker

Getting the application packages

The latest released application package (WAR file) is available from the MEIGarage release page. The latest dev version can be downloaded via nightly.link from the GitHub Action at nightly.link/Edirom/MEIGarage/workflows/maven_docker/main/artifact.zip.

The war file could also be build locally, see Building with Maven.

Running the application packages

Using a running Tomcat (or similar container), you can install the WAR file (see above) in the usual way. In this case, you will need to do some configuration manually:

1. copy the file MEIGarage/WEB-INF/lib/oxgarage.properties to /etc/oxgarage.properties
2. create a directory /var/cache/oxgarage and copy the file log4j.xml to there
3. make the directory owned by the Tomcat user, so that it can create files there: eg chown -R tomcat6:tomcat6 /var/cache/oxgarage
4. make sure the MEI & TEI stylesheets and source are installed at /usr/share/xml/tei using the Debian file hierarchy standard; the distribution files mentioned in the TEI and MEI sources and stylesheets are in the correct layout.

You'll probably need to restart your servlet container to make sure these changes take effect.

Edit the file oxgarage.properties if you need to change the names of directories.

Check the working system by visiting /ege-webclient/ on your Tomcat (or similar) server, and trying an example transformation. You can check the RESTful web server using e.g. Curl. For example, to convert a MEI 3.0 file to Lilypond format, you might do

bash curl -s -o test.ly -F upload=@test.xml http://localhost:8080//ege-webservice/Conversions/mei40%3Atext%3Axml/lilypond%3Atext%3Ax-lilypond/

Building with Maven

The MEIGarage Java project can be built with Maven using

mvn -B package --file pom.xml

Readymade .war files can be downloaded from the GitHub Action using nightly.link. For the required Java version see: https://github.com/Edirom/MEIGarage/blob/6f50fdb96300acc3a8e982cae77265d4a9c96c4a/.github/workflows/maven_docker.yml#L21.

dependencies

The dependencies needed for the Maven build that are not available at the main Maven repository are available through GitHub Packages at the TEIC and Edirom GitHub organizations. While those packages are public, GitHub authentication is needed to access those packages.

To authenticate when building locally, create a GitHub PAT with the read:packages scope. Create a maven settings file or edit an existing one and add it to your .m2 folder (e.g. at /home/name/.m2)

```xml

github

github central https://repo1.maven.org/maven2 githubtei https://maven.pkg.github.com/TEIC/ true githubedirom https://maven.pkg.github.com/Edirom/ true

githubtei YOURGITHUBUSERNAME YOURGITHUBPAT githubedirom SAMEGITHUBUSERNAME SAMEGITHUBPAT

```

Credits

NFDI4Culture

The Consortium for Research Data on Material and Immaterial Cultural Heritage (NFDI4Culture)

The aim of NFDI4Culture is to establish a demand-oriented infrastructure for research data on material and immaterial cultural assets. This includes 2D digitised reproductions of paintings, photographs and drawings as well as 3D digital models of culturally and historically important buildings, monuments or audiovisual data of music, film and stage performances. Concept and structure of the consortium were developed over two years in an open process and in close cooperation between 11 professional societies, 9 supporting institutions and 52 partners. The consortium addresses the needs of a broad spectrum of disciplines from architecture, art, music, theatre, dance, film and media studies.

nfdi4culture.de NFDI4Culture on Mastodon