Configuration
-------------

The application can be configured with a configuration file,
via command line arguments or by environment variables.
If a configuration option is specified in more than one place,
then command line values override environment variables which
override configuration file values which override defaults.

.. Note::

   Configuration options for --oai-pmh-base-url and
   --oai-pmh-admin-email are required.

Some of the configuration options configure the OAI-PMH repository.
Refer to `OAI-PMH`_ protocol description for more information.

This lists some of the available configuration options. Use --help to
list all available options.

.. program:: kuha_oai_serve

.. option:: -h, --help

   Show help message and exit.

.. option:: --print-configuration

   Print active configuration and exit.

.. option:: --port <port>

   Port for serving OAI-PMH Repo Handler. Defaults to ``6003``
   May also be controlled by setting environment variable: ``KUHA_OPRH_PORT``.

.. option:: --oai-pmh-base-url <base_url>

   `OAI-PMH`_ base url. **Required** configuration value.
   May also be controlled by setting environment variable: ``KUHA_OPRH_OP_BASE_URL``.

.. option:: --oai-pmh-admin-email <email>

   `OAI-PMH`_ administrator email address. **Required** configuration value.
   Repeat to give multiple addresses. May also be controlled by setting
   environment variable: ``KUHA_OPRH_OP_EMAIL_ADMIN``.

.. option:: --oai-pmh-repo-name <repo_name>

   `OAI-PMH`_ repository name. Defauts to ``Kuha2 oai-pmh repository``.
   May also be controlled by setting environment variable: ``KUHA_OPRH_OP_REPO_NAME``.

.. option:: --oai-pmh-namespace-identifier <namespace_id>

   Namespace identifier to use with `OAI-Identifiers`_. Set ``None`` to disable
   use of OAI-Identifiers. Defaults to ``None``.
   May also be controlled by setting environment variable: ``KUHA_OPRH_OP_NAMESPACE_ID``.

.. option:: --document-store-url <url>

   Full URL to Kuha document store database. Defaults to ``http://localhost/v0``.
   May also be controlled by setting environment variable: ``KUHA_DS_URL``.

.. option:: --loglevel <loglevel>

   Lowest logging level of log messages that get output. Valid values are
   logging levels supported by Python's :mod:`logging` ``[CRITICAL,ERROR,WARNING,INFO,DEBUG]``.
   Defaults to ``INFO``.
   May also be controlled by setting environment variable: ``KUHA_LOGLEVEL``


**Configuration file**

Args that start with '--' (eg. --document-store-port) can also be set
in a config file. The configuration file lookup searches the file
from current working directory and from the package directory.
The name of the configuration file is ``kuha_oai_pmh_repo_handler.ini``.


.. note:: Invoke with ``--help`` to print out config file lookup paths.


**Environment variables**

If the program will be run by using the scripts provided in ``scripts``
subdirectory, the runtime environment can be controlled via ``scripts/runtime_env``,
which will be created by copying from ``scripts/runtime_env.dist`` at
installation time by ``scripts/install_kuha_oai_pmh_repo_handler_virtualenv.sh``.


.. _oai-pmh: http://www.openarchives.org/OAI/openarchivesprotocol.html
.. _oai-identifiers: http://www.openarchives.org/OAI/2.0/guidelines-oai-identifier.htm