kerko | web application component that provides a faceted search | Search Engine library

This section only applies if you intend to integrate Kerko into your own application. If you are more interested into the standalone KerkoApp application, please refer to its installation instructions. We'll assume that you have some familiarity with Flask and suggest steps for building a minimal app, let's call it hello_kerko.py, to get you started. You have just built a really minimal application for Kerko. This code example is available at KerkoStart. See also KerkoApp for a slightly more complete example.
The first step is to install Kerko. As with any Python library, it is highly recommended to install Kerko within a virtual environment. Once the virtual environment is set and active, use the following command: pip install kerko
In hello_kerko.py, configure variables required by Kerko and create your app object, as in the example below: import pathlib from flask import Flask from kerko.composer import Composer app = Flask(__name__) app.config['SECRET_KEY'] = '_5#y2L"F4Q8z\n\xec]/' # Replace this value. app.config['KERKO_ZOTERO_API_KEY'] = 'xxxxxxxxxxxxxxxxxxxxxxxx' # Replace this value. app.config['KERKO_ZOTERO_LIBRARY_ID'] = '9999999' # Replace this value. app.config['KERKO_ZOTERO_LIBRARY_TYPE'] = 'group' # Replace this value if necessary. app.config['KERKO_DATA_DIR'] = str(pathlib.Path(__file__).parent / 'data' / 'kerko') app.config['KERKO_COMPOSER'] = Composer() SECRET_KEY: This variable is required for generating secure tokens in web forms. It should have a secure, random value and it really has to be secret. It is usually set in an environment variable rather than in Python code, to make sure it never ends up in a code repository. But here we're taking the minimal route and thus are cutting some corners! KERKO_ZOTERO_API_KEY, KERKO_ZOTERO_LIBRARY_ID and KERKO_ZOTERO_LIBRARY_TYPE: These variables are required for Kerko to be able to access your Zotero library. See Configuration variables for details on how to properly set these variables. KERKO_DATA_DIR: This variable specifies the directory where to store the search index and the file attachments. If the specified directory does not already exists, Kerko will try to create it. KERKO_COMPOSER: This variable specifies key elements needed by Kerko, e.g., fields for display and search, facets for filtering. These are defined by instantiating the Composer class. Your application may manipulate the resulting object at configuration time to add, remove or alter fields, facets, sort options, search scopes, citation download formats, or badges. See Kerko Recipes for some examples.
Also configure the Flask-Babel and Bootstrap-Flask extensions: from flask_babel import Babel from flask_bootstrap import Bootstrap babel = Babel(app) bootstrap = Bootstrap(app) See the respective docs of Flask-Babel and Bootstrap-Flask for more details.
Instantiate the Kerko blueprint and register it in your app: from kerko import blueprint as kerko_blueprint app.register_blueprint(kerko_blueprint, url_prefix='/bibliography') The url_prefix argument defines the base path for every URL provided by Kerko.
In the same directory as hello_kerko.py with your virtual environment active, run the following shell commands: export FLASK_APP=hello_kerko.py flask kerko sync Kerko will retrieve your bibliographic data from zotero.org. If you have a large bibliography or large attachments, this may take a while (and there is no progress indicator). In production use, that command is usually added to the crontab file for regular execution (with enough time between executions for each to complete before the next one starts). To list all commands provided by Kerko: flask kerko --help
Run your application: flask run
Open http://127.0.0.1:5000/bibliography/ in your browser and explore the bibliography.