Kustvakt is a user and policy management component for KorAP (Diewald et al., 2016). It manages user access to resources (i.e. corpus data) typically bound with some licensing schemes. The licensing schemes of IDS resources provided through KorAP (DeReKo) are very complex involving the user access location and purposes (Kupietz & Lüngen, 2014). To manage user access to resources, Kustvakt performs query rewriting with document restrictions (Bański et al., 2014).
Kustvakt acts as a middleware in KorAP binding other components, such as Koral a query serializer and Krill a search component, together. As the KorAP's API provider, it provides services, e.g. searching and retrieving annotation data of a match/hit, that can be used by a KorAP client, e.g. Kalamar (a KorAP web user interface) and KorapSRU (the CLARIN FCS endpoint for KorAP).
Kustvakt lite version
provides basic services including search, match info, statistic and annotation services, without user and policy management.
Kustvakt full version
provides user and policy management and extended services, in addition to the basic services. This version requires a database (Sqlite is provided) and an LDAP system for user authentication.
Recent changes on the project are described in the change logs (Changes files).
Web-services including their usage examples are described in the wiki.
Prerequisites: Jdk 1.8, Git, Maven 3
Clone the latest version of Kustvakt
git clone email@example.com:KorAP/Kustvakt.git
Install Kustvakt-core in your maven local repository
cd Kustvakt/core mvn clean install
Package Kustvakt full version
cd ../full mvn clean package
The jar file is located in the
Package Kustvakt lite version
cd ../lite mvn clean package
The jar file is located in the
Customizing Kustvakt configuration
Copy the default Kustvakt configuration file (e.g.
lite/src/main/resources/kustvakt-lite.conf), to the same folder as the Kustvakt jar files (
/target). Please do not change the name of the configuration file.
Setting Index Directory
Set krill.indexDir in the configuration file to the location of your Krill index (relative path to the jar). In Kustvakt's root directory, there is a sample index, e.g.
krill.indexDir = ../../sample-index
Set the location of the LDAP configuration file for Kustvakt full version. The file should contain an admin password to access an LDAP system. Without LDAP, user authentication functions and services cannot be used. Authentication mechanism can be extended by implementing other authentication methods e.g. using a database.
ldap.config = path-to-ldap-password
Setting BasicAuthentication for Testing
For testing, you can use/activate BasicAuthentication, see Spring XML configuration file for testing at
/full/src/test/resources/test-config.xml. BasicAuthentication uses a dummy UserDao allowing all users to be authenticated users. You can implement UserDao by connecting it to a user table in a database and checking username and password for authentication.
<bean id="basic_auth" class="de.ids_mannheim.korap.authentication.BasicAuthentication" /> <util:list id="kustvakt_authproviders" value-type="de.ids_mannheim.korap.interfaces.AuthenticationIface"> <ref bean="basic_auth" /> ... </util:list>
Optional Custom Configuration
Changing Kustvakt Server Port and Host
Server.port = 8089 Server.host = localhost
Changing Kustvakt Service Base URL
The default base URL is
Setting Default Foundries
These properties define the default foundries used for specific layers, for instance in a rewrite, a default foundry may be added to a Koral query missing a foundry.
default.foundry.partOfSpeech = tt default.foundry.lemma = tt default.foundry.orthography = opennlp default.foundry.dependency = malt default.foundry.constituent = corenlp
Running Kustvakt Server
kustvakt-lite.conf in the same folder as the jar file. Otherwise assuming sample-index located in the parent directory of the jar file.
Kustvakt full version requires an LDAP configuration file containing an admin password to access an LDAP system. You can still run Kustvakt full version without an LDAP system, but user authentication functions and services cannot be used. Only services for guest/demo user would be available.
java -jar target/Kustvakt-[lite/full]-[version].jar
To run Kustvakt with a custom spring XML configuration file, it must be included in the classpath. For instance:
custom-spring-config.xml is located in
config folder must be included in the classpath with
cd target/ java -cp Kustvakt-full-[version].jar:config de.ids_mannheim.korap.server.KustvaktServer --spring-config custom-spring-config.xml
Shutting down Kustvakt Server
Kustvakt server can be shut down by sending a POST request with a shutdown token. When Kustvakt server is started, a shutdown token is automatically generated and written to a
shutdownToken file with the following format:
A shutdown request can be sent as follows.
curl -H "Content-Type: application/x-www-form-urlencoded" "http://localhost:8089/shutdown" -d @shutdownToken
Advanced setup such as setting database properties and configuring mail settings for email notifications, are described in the wiki.
Kustvakt is published under the BSD-2 License. It is developed as part of the KorAP Corpus Analysis Platform at the Institute for German Language (IDS), funded by the Leibniz-Gemeinschaft and supported by the KobRA project, funded by the Federal Ministry of Education and Research (BMBF).
Contributions to Kustvakt are very welcome!
Ideally, any contributions should be committed via KorAP Gerrit server to facilitate code reviewing (see Gerrit Code Review - A Quick Introduction). However, we are also happy to accept comments and pull requests via GitHub.
Please note that unless you explicitly state otherwise any contribution intentionally submitted for inclusion into Kustvakt shall – as Kustvakt itself – be under the BSD-2 License.
Diewald, Nils/Hanl, Michael/Margaretha, Eliza/Bingel, Joachim/Kupietz, Marc/Bański, Piotr/Witt, Andreas (2016): KorAP Architecture – Diving in the Deep Sea of Corpus Data. In: Calzolari, Nicoletta/Choukri, Khalid/Declerck, Thierry/Goggi, Sara/Grobelnik, Marko/Maegaard, Bente/Mariani, Joseph/Mazo, Helene/Moreno, Asuncion/Odijk, Jan/Piperidis, Stelios (Hrsg.): Proceedings of the Tenth International Conference on Language Resources and Evaluation (LREC 2016), Portorož, Slovenia. Paris: European Language Resources Association (ELRA), 2016. S. 3586-3591.
Bański, Piotr/Diewald, Nils/Hanl, Michael/Kupietz, Marc/Witt, Andreas (2014): Access Control by Query Rewriting. The Case of KorAP. In: Proceedings of the Ninth Conference on International Language Resources and Evaluation (LREC’14). European Language Resources Association (ELRA), 2014. S. 3817-3822.
Kupietz, Marc/Lüngen, Harald (2014): Recent Developments in DeReKo. In: Calzolari, Nicoletta et al. (eds.): Proceedings of the Ninth International Conference on Language Resources and Evaluation (LREC'14). Reykjavik: ELRA, 2378-2385.