commit | 10e7847cf514f52ed7278073e871d4b3aeff9557 | [log] [tgz] |
---|---|---|
author | Akron <nils@diewald-online.de> | Tue Dec 14 10:02:00 2021 +0100 |
committer | Akron <nils@diewald-online.de> | Tue Dec 14 10:02:00 2021 +0100 |
tree | a1af81c7ed569b2b67e4de16134af6f5bd8df89c | |
parent | f898d7bdac0a5251514e33cab08953550e9a8533 [diff] |
Fix word issue in tour Change-Id: I1b981e443b19d8279bd563b48e8ef395593909fd
Kalamar is a Mojolicious-based user interface frontend for the KorAP Corpus Analysis Platform.
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.
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.
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
.
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 git://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
.
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.
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).
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.)
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.
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.
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/Piwikmake
not available under WindowsInstead of running
$ perl Makefile.PL $ make test
it is also possible to run the test suite using prove
.
$ prove -lr t
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
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
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.
Copyright (C) 2015-2021, IDS Mannheim
Author: Nils Diewald, Helge Stallkamp
Contributor: Eliza Margaretha (Documentation), Susanne Feix (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.
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).