Skip to content

How to upgrade

From 0.9 to 1.0.x

Version 1.0.x brings significant changes on how Kerko can be configured. Before you attempt an upgrade, reading Configuration basics is a must.


The instructions below make the assumption that you have cloned KerkoApp from its Git repository.

  • Go to the KerkoApp directory.
  • Rename the default branch of your local KerkoApp repository:

    git branch -m master main
    git fetch origin
    git branch -u origin/main main
    git remote set-head origin -a
  • Get the desired version of KerkoApp. You may check the list of available versions. For version 1.0.0, for example, replace VERSION with 1.0.0 in the command below:

    git checkout VERSION
  • Activate your Python virtual environment.

  • Install Python dependencies:

    pip install --force-reinstall -r requirements/run.txt
  • Rename the .env file to dotenv.old. We no longer want KerkoApp to use that file, but it might be useful to keep it as reference while we migrate the configuration.

  • Create two files, .secrets.toml and config.toml, in the KerkoApp directory, i.e., the directory where is found.
  • Copy the SECRET_KEY and KERKO_ZOTERO_API_KEY lines from dotenv.old into .secrets.toml. In .secrets.toml, rename the KERKO_ZOTERO_API_KEY parameter to ZOTERO_API_KEY. For each of the two parameters, make sure the value following the equal sign (=) is surrounded by double quotes ("). To ascertain the syntax, you may have a look at the sample.secrets.toml file provided by KerkoApp.
  • Copy the remaining lines from dotenv.old to config.toml. For each parameter, use the list below to determine if something special needs to be done to migrate it. Almost all configuration parameters have been renamed and/or moved into a hierarchical structure (indicated by an arrow (→)). Check the parameter values too as the syntax of a TOML file is slightly different from that of a .env file, e.g., in TOML string values must be surrounded by double quotes ("), and booleans values must be either true or false (lowercase, no quotes). Refer to the parameters documentation for additional information, and have a look at the sample.config.toml file provided by KerkoApp.
    • DEBUG: Remove. Debug mode is now activated with the --debug command line option.
    • FLASK_APP: Probably not needed anymore. In doubt, please refer to the Flask documentation on application discovery. If you do need this variable, then a .env file could be the right place. It will not work from a TOML file. Note also that the application is now referenced as instead of
    • FLASK_ENV: Remove. Flask 2.3 stopped supporting it. Debug mode is now activated with the --debug command line option.
    • KERKO_BOOTSTRAP_VERSIONkerko.assets.bootstrap_version
    • KERKO_CSL_STYLEkerko.zotero.csl_style
    • KERKO_COMPOSERkerko_composer
    • KERKO_DATA_DIRDATA_PATH. Now optional, relative to the instance path, and defaulting to kerko instead of data/kerko.
    • KERKO_DOWNLOAD_ATTACHMENT_NEW_WINDOWkerko.features.download_attachment_new_window
    • KERKO_DOWNLOAD_CITATIONS_LINKkerko.features.download_results
    • KERKO_DOWNLOAD_CITATIONS_MAX_COUNTkerko.features.download_results_max_count
    • KERKO_FEEDSkerko.feeds.formats
    • KERKO_FEEDS_FIELDSkerko.feeds.fields
    • KERKO_FEEDS_MAX_DAYSkerko.feeds.max_days
    • KERKO_FEEDS_REJECT_ANYkerko.feeds.reject_any
    • KERKO_FEEDS_REQUIRE_ANYkerko.feeds.require_any
    • KERKO_HIGHWIREPRESS_TAGSkerko.meta.highwirepress_tags
    • KERKO_JQUERY_VERSIONkerko.assets.jquery_version
    • KERKO_PAGE_LENkerko.pagination.page_len
    • KERKO_PAGER_LINKSkerko.pagination.pager_links
    • KERKO_POPPER_VERSIONkerko.assets.popper_version
    • KERKO_PRINT_CITATIONS_LINKkerko.features.print_results
    • KERKO_PRINT_CITATIONS_MAX_COUNTkerko.features.print_results_max_count
    • KERKO_PRINT_ITEM_LINKkerko.features.print_item
    • KERKO_RELATIONS_INITIAL_LIMITkerko.features.relations_initial_limit
    • KERKO_RELATIONS_LINKSkerko.features.relations_links
    • KERKO_RELATIONS_SORTkerko.features.relations_sort
    • KERKO_RESULTS_ABSTRACTSkerko.features.results_abstracts
    • KERKO_RESULTS_ABSTRACTS_MAX_LENGTHkerko.features.results_abstracts_max_length
    • KERKO_RESULTS_ABSTRACTS_MAX_LENGTH_LEEWAYkerko.features.results_abstracts_max_length_leeway
    • KERKO_RESULTS_ABSTRACTS_TOGGLERkerko.features.results_abstracts_toggler
    • KERKO_RESULTS_ATTACHMENT_LINKSkerko.features.results_attachment_links
    • KERKO_RESULTS_URL_LINKSkerko.features.results_url_links
    • KERKO_TEMPLATE_ATOM_FEEDkerko.templates.atom_feed
    • KERKO_TEMPLATE_BASEkerko.templates.base
    • KERKO_TEMPLATE_ITEMkerko.templates.item
    • KERKO_TEMPLATE_LAYOUTkerko.templates.layout
    • KERKO_TEMPLATE_SEARCH_ITEMkerko.templates.search_item
    • KERKO_TITLEkerko.meta.title
    • KERKO_WITH_JQUERYkerko.assets.with_jquery
    • KERKO_WITH_POPPERkerko.assets.with_popper
    • KERKO_ZOTERO_BATCH_SIZEkerko.zotero.batch_size
    • KERKO_ZOTERO_LOCALEkerko.zotero.locale
    • KERKO_ZOTERO_MAX_ATTEMPTSkerko.zotero.max_attempts
    • KERKO_ZOTERO_WAITkerko.zotero.wait
    • KERKOAPP_CHILD_EXCLUDE_REkerko.zotero.child_exclude_re
    • KERKOAPP_CHILD_INCLUDE_REkerko.zotero.child_include_re
    • KERKOAPP_COLLECTION_FACETSkerko.facets.*. See sub-parameters type (set it to "collection"), collection_key, weight, and title.
    • KERKOAPP_EXCLUDE_DEFAULT_BADGES: Remove. There is no replacement since Kerko does not provide any default badges at this point.
    • KERKOAPP_EXCLUDE_DEFAULT_CITATION_FORMATSkerko.citation_formats.*. See sub-parameter enable.
    • KERKOAPP_EXCLUDE_DEFAULT_FACETSkerko.facets.*. See sub-parameter enable.
    • KERKOAPP_EXCLUDE_DEFAULT_FIELDSkerko.search_fields.*. See sub-parameter enable.
    • KERKOAPP_EXCLUDE_DEFAULT_SCOPESkerko.scopes.*. See sub-parameter enable.
    • KERKOAPP_EXCLUDE_DEFAULT_SORTSkerko.sorts.*. See sub-parameter enable.
    • KERKOAPP_FACET_INITIAL_LIMIT_LEEWAYkerko.facets.*.initial_limit_leeway. This is now set individually for each facet, and there is no longer a global parameter.
    • KERKOAPP_FACET_INITIAL_LIMITkerko.facets.*.initial_limit. This is now set individually for each facet, and there is no longer a global parameter.
    • KERKOAPP_ITEM_EXCLUDE_REkerko.zotero.item_exclude_re
    • KERKOAPP_ITEM_INCLUDE_REkerko.zotero.item_include_re
    • KERKOAPP_MIME_TYPESkerko.zotero.attachment_mime_types
    • KERKOAPP_TAG_EXCLUDE_REkerko.zotero.tag_exclude_re
    • KERKOAPP_TAG_INCLUDE_REkerko.zotero.tag_include_re
    • PROXY_FIXkerkoapp.proxy_fix.*
  • If you are using a translated version of Kerko, the default "Bibliography" link of the navigation bar no longer gets translated because it is now defined by a configuration parameter. To replace it, set the kerko.link_groups.navbar parameter (see the parameters documentation for details).
  • If your configuration changes neither the DATA_PATH nor the INSTANCE_PATH parameters, then rename KerkoApp's data directory to instance.
  • Make sure your WSGI server now references the application as (or wsgi:app) instead of (or kerkoapp:app).
  • Rebuild your search index using the following commands, then restart the application:

    flask kerko clean index
    flask kerko sync index
  • Restart the application.

Custom templates

Occurrences of parameter names in custom templates will need to be edited. For example:

  • config.KERKO_COMPOSERconfig.kerko_composer
  • config.KERKO_TITLEconfig.kerko.meta.title
  • ... for the full list, please refer to the above section.

The following item fields have been renamed. Occurrences of these in your templates will need to be edited:

  • z_dateAddeddate_added
  • z_dateModifieddate_modified

The following views have been renamed. Occurrences of these in your templates (perhaps in calls to url_for) will need to be edited:

  • item_citation_downloaditem_bib_download
  • search_citation_downloadsearch_bib_download

Custom applications

Configuration initialization and loading has greatly changed. If you have a custom application, it will need to be adapted even if you do not plan to use TOML files. See Creating a custom application for a working example, and refer to the changelog for other breaking changes.