TEIGarage is a webservice and RESTful service to transform, convert and validate various formats, focussing on the TEI format. TEIGarage 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 TEIGarage can be found at teigarage.tei-c.org.
Open API documentation can be found at https://github.com/TEIC/TEIGarage/blob/main/src/main/webapp/openapi.json or at the running instance https://teigarage.tei-c.org/ege-webservice/. A curl example call to the API to convert an existing .docx to a TEI file looks like
curl -o output.xml -F upload=@input.docx https://teigarage.tei-c.org/ege-webservice/Conversions/docx%3Aapplication%3Avnd.openxmlformats-officedocument.wordprocessingml.document/TEI%3Atext%3Axml/
With Docker installed, a readymade image can be fetched from the GitHub Container Registry or from DockerHub.
docker pull ghcr.io/teic/teigarage:latest
docker run --rm \
-p 8080:8080 \
-e WEBSERVICE_URL=http://localhost:8080/ege-webservice/ \
--name teigarage ghcr.io/teic/teigarageOnce it's running, you can point your browser at http://localhost:8080 for the graphical user interface and http://localhost:8080/ege-webservice` for the webservice.
You can also get the development version from DockerHub using docker pull teic/teigarage:dev.
-
WEBSERVICE_URL : The full URL of the RESTful web service. This is relevant for the web client (aka the GUI) if you are running the docker container on a different port or with a different URL.
-
-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
When the docker image is build, the latest releases of the TEI 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 |
Using your local folders for the TEI sources and stylesheets:
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 \
--name teigarage ghcr.io/teic/teigarageYou can also change the version that is used by supplying different version number when building the image locally running something like
docker build \
--build-arg VERSION_STYLESHEET=7.52.0 \
--build-arg VERSION_ODD=4.3.0 \
.in your local copy of the TEIGarage.
The Docker image exposes two ports, 8080 and 8081. If you're running TEIGarage over plain old HTTP, use the 8080 connector. For HTTPS connections behind a SSL terminating Load Balancer, please use the 8081 connector.
The latest released application package (WAR file) is available from the TEIGarage release page. The latest dev version can be downloaded via nightly.link from the GitHub Action at nightly.link/TEIC/TEIGarage/workflows/maven_docker/main/artifact.zip.
The war file could also be build locally, see Building with Maven.
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:
- copy the file TEIGarage/WEB-INF/lib/oxgarage.properties to
/etc/oxgarage.properties - create a directory
/var/cache/oxgarageand copy the file log4j.xml to there - make the directory owned by the Tomcat user, so that it can create files there: eg
chown -R tomcat6:tomcat6 /var/cache/oxgarage - make sure the TEI stylesheets and source are installed at
/usr/share/xml/teiusing the Debian file hierarchy standard; the distribution files mentioned in the TEI 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 TEI file to Word docx format, you might do
curl -s -o test.docx -F upload=@test.xml http://localhost:8080/ege-webservice/Conversions/TEI%3Atext%3Axml/docx%3Aapplication%3Avnd.openxmlformats-officedocument.wordprocessingml.documentThe TEIGarage 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:
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)
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
http://maven.apache.org/xsd/settings-1.0.0.xsd">
<activeProfiles>
<activeProfile>github</activeProfile>
</activeProfiles>
<profiles>
<profile>
<id>github</id>
<repositories>
<repository>
<id>central</id>
<url>https://repo1.maven.org/maven2</url>
</repository>
<repository>
<id>githubtei</id>
<url>https://maven.pkg.github.com/TEIC/*</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
</repositories>
</profile>
</profiles>
<servers>
<server>
<id>githubtei</id>
<username>YOURGITHUBUSERNAME</username>
<password>YOURGITHUBPAT</password>
</server>
</servers>
</settings>