03cc36817854ca1cea5887f2d7c5d144c700f765 - KorAP/Kalamar

commit	03cc36817854ca1cea5887f2d7c5d144c700f765	[log] [tgz]
author	Marc Kupietz <kupietz@ids-mannheim.de>	Mon Dec 16 14:20:54 2024 +0100
committer	Marc Kupietz <kupietz@ids-mannheim.de>	Mon Dec 16 16:28:03 2024 +0100
tree	1ff59c1d23a4f2757161b13d2935e487dabd3c64
parent	ed223bef6416012177f268223a2f2d5ce1c0b8b5 [diff]

tree: 1ff59c1d23a4f2757161b13d2935e487dabd3c64

README.md

Kalamar

Kalamar is a Mojolicious-based user interface frontend for the KorAP Corpus Analysis Platform.

Kalamar Screenshots

Setup

The easiest way to install and run Kalamar is using Docker.

docker pull korap/kalamar

Then start Kalamar listening on port 64543.

docker run --network host --name kalamar korap/kalamar

Kalamar will be available at http://localhost:64543.

See the description on docker hub regarding further information.

Setup for Development

To install the latest version of Kalamar, first fetch the resource ...

git clone https://github.com/KorAP/Kalamar

... and follow the steps below.

If you have any problems with installing Kalamar, see the Troubleshooting section.

Generate Static Asset Files

To generate the static asset files (scripts, styles, images ...), you need NodeJS >= 6.0.0. This will probably need administration rights, depending on your installation path. These tools may also be available with a package manager.

You can check your version using

npm -v

Afterwards you can install the dependencies and run grunt to create the assets.

cd Kalamar
npm install -g grunt-cli
npm install
grunt

Whenever the assets change, just rerun npm install and grunt.

Start Server

Kalamar uses the Mojolicious framework, that expects a Perl version of at least 5.16. On Windows Strawberry Perl is recommended. An environment based on Perlbrew is recommended, if available. The installation guide requires App::cpanminus as well.

Some perl modules are not on CPAN yet, so you need to install them from GitHub. The easiest way to do this is using App::cpanminus. This will probably need administration rights.

cpanm https://github.com/Akron/Mojolicious-Plugin-Localize.git

Then install the dependencies using App::cpanminus (there is no need to install Kalamar) and run the test suite.

cd Kalamar
cpanm --installdeps .
perl Makefile.PL
make test

Kalamar can be deployed like all Mojolicious apps. The easiest way is to start the built-in server:

perl script/kalamar daemon

Kalamar will then be available at localhost:3000 in your browser.

By default, Kalamar tries to connect to https://korap.ids-mannheim.de/api/, followed by the most current version of the API. You may change that endpoint to the KorAP API provider in the configuration (see Kustvakt for further information) or by using the environment variable KALAMAR_API.

If the endpoint is remote and requires SSL support, like the default endpoint, you have to install SSL support in addition:

cpanm IO::Socket::SSL

Updates

To update Kalamar, just run

git pull origin master
cpanm --installdeps .
npm install
grunt

And both the server and client dependencies should be up to date.

Configuration

The basic configuration file is kalamar.conf. To define derivations, create a configuration file with the pattern kalamar.myconf.conf and follow the descriptions in kalamar.conf.

To start Kalamar with a derivative configuration, set the MOJO_MODE environment variable.

MOJO_MODE=myconf perl script/kalamar daemon

Or in the windows command line with:

> cmd /C "set MOJO_MODE=qr && perl .\script\kalamar daemon"

Or in the windows powershell with:

> $env:MOJO_MODE='myconf'; perl .\script\kalamar daemon; Remove-Item Env:\MOJO_MODE

For client-side configurations, a file kalamar.conf.js can be introduced, that will be consulted during the build process, loading optional components using a require(...) directive (see example below).

Secret file

Kalamar uses auto rotating secrets. Allow access to a file called kalamar.secret.json in the home directory of kalamar. It will automatically be created, if it doesn't exist. (kalamar.secret is deprecated.)

Localization

To create a localized version of Kalamar, start the localize command with the target locale as its argument, e.g. pl for polish.

perl script/kalamar localize pl

The newly defined dictionary file can then be modified and added to the resources definition of the Localize plugin in the configuration:

Localize => {
  resources => ['kalamar.pl.dict']
}

To localize example queries according to a special corpus environment, define a name of the example corpus in the configuration.

Kalamar => {
  examplecorpus => 'mycorpus'
}

Then create a translation file based on kalamar.queries.dict as a blueprint and add it to the Localize resource list.

Templates can be localized and customized by overriding the Template dictionary entries.

Currently the JavaScript translations are separated and stored in dev/js/src/loc. To generate assets relying on different locales, add the locale to Gruntfile.js.

To localize the annotation helper according to a special corpus environment, different annotation foundries can be loaded in kalamar.conf.js. For example to support marmot and malt, the configuration may look like this:

require([
  "hint/foundries/marmot",
  "hint/foundries/malt"
]);

See dev/js/src/hint/foundries for more optional foundries.

Customization

The landing page can be customized by overriding the entry for Template_intro in the dictionary.

Some sections of the user interface can be customized by adding new content blocks. Currently the documented sections are in footer, in the bottom line of the user interface, sidebar, in the left part of the user interface if present, headerButtonGroup, in the right top part of the user interface, and loginInfo, below the login form if present.

Plugins

Some plugins are bundled as part of Kalamar. Plugins can be loaded via configuration file in an array

{
  Kalamar => {
    plugins => ['Auth']
  }
}

Currently bundled plugins are

Auth: For integrating user management supported by Kustvakt full.
Piwik: For integrating Matomo/Piwik.
Tei2KorAPXML: For integrated calls to tei2korapxml, if installed.
KorAPXML2Krill: For integrated calls to korapxml2krill, if installed.
KrillIndexer: For integrated calls to Krilll, if installed and exposed by KRILL_INDEXER_PATH.
KorAPXML2CoNLLU: For integrated calls to conllu2korapxml and korapxml2conllu, if installed.

Maintaining

Caching

Kalamar supports CHI for caching, allowing various cache drivers to configure.

To see options for cache maintenance (e.g. to clear search results after index update), run the command

perl script/kalamar chi

Troubleshooting

`make` not available under Windows

Instead of running

perl Makefile.PL
make test

it is also possible to run the test suite using prove.

prove -lr t

Problem installing Crypt::Random::Source on Windows

Crypt::Random::Source recently removed support for C as a random source, which may lead to missing sources in tests under certain operating systems. You should be able to force install Crypt::Random::Source, though this environment is not recommended for production:

cpanm -f Crypt::Random::Source

Problem installing Mojolicious::Plugin::MailException on Windows

Some versions of Mojolicious::Plugin::MailException have a minor bug in the test suite, so a force install may be necessary.

cpanm -f Mojolicious::Plugin::MailException

Problem running scripts on Windows with Powershell

In case you are having issues with running scripts under Windows, you can set the execution policy with Set-ExecutionPolicy. If using the RemoteSigned execution policy, you can use Unblock-File to allow specific scripts to run.

Problem installing Module::Pluggable

In case Module::Pluggable fails as a dependency of the DateTime module, just force the installation and ignore warnings.

cpanm --force Module::Pluggable

COPYRIGHT AND LICENSE

Original Software

Copyright (C) 2015-2024, IDS Mannheim
Author: Nils Diewald, Helge Stallkamp
Contributor: Uyen-Nhu Tran, Eliza Margaretha (Documentation), Susanne Feix and Rebecca Wilm (Translation), Leo Repp

Kalamar is developed as part of the KorAP Corpus Analysis Platform at the Leibniz Institute for the German Language (IDS), member of the Leibniz Association and supported by the KobRA project, funded by the Federal Ministry of Education and Research (BMBF).

Kalamar is free software published under the BSD-2 License.

To cite this work, please refer to:
Diewald, Nils, Barbu Mititelu, Verginica and Kupietz, Marc (2019): The KorAP user interface. Accessing CoRoLa via KorAP. In: Cosma, Ruxandra/Kupietz, Marc (eds.), On design, creation and use of of the Reference Corpus of Contemporary Romanian and its analysis tools. CoRoLa, KorAP, DRuKoLA and EuReCo, Revue Roumaine de Linguistique, 64(3). Editura Academiei Române, Bucharest, Romania.

Bundled Assets

The KorAP logo was designed by Norbert Cußler-Volz is released under the terms of the Creative Commons License BY-NC-ND 4.0. ALERTIFY.js is released under the terms of the MIT License. Almond is released under the terms of the BSD License. dagre is released under the terms of the MIT License. Highlight.js is released under the terms of the BSD License. Jasmine is released under the terms of the MIT License. RequireJS is released under the terms of the BSD License. Font Awesome by Dave Gandy is released under the terms of the SIL OFL 1.1. Benchmark.js is released under the terms of the MIT License. lodash is released under the terms of the MIT License. Platform.js is released under the terms of the MIT License. INTRO.JS is released under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE (GNU AGPLv3).