THIS REPOSITORY IS OBSOLETE.

For Annif the similar functionality as offered by Maui is now available by MLLM backend.

Maui Server: A topic indexing server based on Maui

This is Maui Server, an HTTP wrapper around the Maui Topic Indexer.

Maui Server provides a topic indexing service. It automatically determines the main topics of a text, with candidate topics coming from a SKOS vocabulary. It requires training data—documents with previously assigned topics—to work. Maui Server is a Java web application and provides RESTful, JSON-based APIs (see API documentation).

Download and Installation

Requirements: Maui Server requires a Java Servlet Container such as Apache Tomcat or Jetty to run.

Download: Maui Server is distributed as a war file (mauiserver-X.Y.Z.war). It can be downloaded here. The very latest pre-release version can also be built from the source repository, see below.

Installation: To install and run it, deploy the war file into the servlet container (usually by copying it into the container's webapps directory, maybe after renaming it).

Configuring the data directory

Maui Server needs a data directory on the file system where it keeps its data. This directory is established in the following way:

1. If the Java system property MauiServer.dataDir is set, use its value. (This can be set on the Java command line via -DMauiServer.dataDir=...)
2. Otherwise, if the OS environment variable MAUI_SERVER_DATA_DIR is set, use its value. (How to set this depends on the operating system.)
3. Otherwise, use a subdirectory data in the current directory, from where Maui Server was started.

The directory must already exist, otherwise initialisation will fail.

Configuring the default language

By default, Maui Server assumes that vocabulary and content are in English. The global language can be set using the Java system property MauiServer.defaultLang, or the OS environment variable MAUI_SERVER_DEFAULT_LANG. Supported values are en, (English), fr (French), es (Spanish) and de (German). The default language can be overridden on a per-tagger basis using the lang key in the configuration.

Setting up authentication

A simple recipe for securing Maui Server behind a username/password:

1. Uncomment the <security-constraint>/<login-config> sections in web.xml

2. Add a user with role maui-server to your servlet container configuration; for Tomcat, this could mean adding to /conf/tomcat-users.xml:

   <role rolename="maui-server"/>
   <user username="admin" password="password" roles="maui-server"/>
   

API documentation

See API.md.

Building and Running from Source

The project uses Maven for building.

• mvn package creates a war file in the /target directory, for deployment with a servlet container such as Tomcat or Jetty.
• mvn jetty:run runs Maui Server directly, using Jetty. The server will start up at http://localhost:8080/ . This can be convenient for testing. Add -Djetty.http.port=6666 to run on a different port.

The API root is at /. A small demo app is at /app/ (requires tagger creation and training through the API).

Usage with Docker

• Pull Maui Server image from repository:

  docker pull quay.io/natlibfi/mauiserver

• Alternatively, build the image locally:

  docker build -t quay.io/natlibfi/mauiserver .

• Run as the host user and mount mauidata directory located on host:

  docker run -e MY_UID=$(id -u) -e MY_GID=$(id -g) -v ~/mauidata:/mauidata --name mauiserver --rm --network="host" quay.io/natlibfi/mauiserver

• Alternatively, run as root and use a named volume for mauidata directory:

  docker run -v mauidata-volume:/mauidata --name mauiserver --rm --network="host" quay.io/natlibfi/mauiserver

The Maui Server can then be accessed from host system in http://localhost:8080/mauiserver/. In case of connection problems, try replacing --network="host" option with -p 8080:8080.

License

This project is licensed under the terms of the GNU GPL v3.

Version history

1.3.1 (in development)

• TODO

1.3.0 (2019-09-27)

• Add WEKA classifier API
• Update various libraries
• Require Java 8

1.2.1 (2016-12-18)

• Patch maui.war to turn off unhelpful logging to ./out/learning.log

1.2.0 (2016-09-27)

• Make probability threshold for suggested tags configurable
• Fix a regression where training/cross-validation jobs with exception were marked complete
• Don't automatically delete training model when vocabulary is updated

1.1.0 (2016-08-02)

• Add cross-validation API to compute precision and recall
• Make maximum number of recommendations returned per document configurable
• Add "version" key to / resource
• Bugfix: Problems with tagger ID capitalization (#1)
• Empty text to suggest API now responds 400 instead of 200
• Make logging more informative and less verbose
• Require Java 7

1.0.1 (2016-02-11)

• Better support for running with Tomcat authentication
• Improved error messages
• Bugfix: make root resource work when no trailing slash in URL
• Disallow \ and / in tagger ID to avoid a Tomcat issue

1.0.0 (2015-08-24)

Initial release.