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

The application can be configured with a configuration file,
via command line arguments or by environment variables.
All configuration options have default values.
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.

The following configuration options are available:

.. program:: kuha_osmh_serve

.. option:: -h, --help

   Show help message and exit.

.. option:: --print-configuration

   Print active configuration and exit.

.. option:: --stream-response

   Switch to enable streaming from ListRecordHeaders endpoint. Defaults to ``False``.
   May also be controlled by setting environment variable: ``KUHA_OSMH_STREAM_RESPONSE``.

.. option:: --port <port>

   Port for serving OSMH Repo Handler. Defaults to ``6002``
   May also be controlled by setting environment variable: ``KUHA_ORH_PORT``.

.. option:: --osmh-repo-handler-api-version <api_version>

   Api version for OSMH Repo Handler. This gets prepended to the URL path.
   Defaults to ``v0``. May also be controlled by setting environment
   variable: ``KUHA_OSMH_API_VERSION``.

.. option:: --query-limit <limit>

   Optional query limit for configuring the limit of records per query
   when fetching multiple records from Document Store. Set 0 to disable.
   Defaults to ``0``. May also be controlled by setting environment
   variable: ``KUHA_OSMH_QUERY_LIMIT``.

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

   Host & scheme of Kuha Document Store. Defaults to ``http://localhost``.
   May also be controlled by setting environment variable: ``KUHA_DS_HOST``.

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

   Port of Kuha document store database. Defaults to ``6001``.
   May also be controlled by setting environment variable: ``KUHA_DS_PORT``.

.. option:: --document-store-api-version <api_version>

   Api version for document store. This gets prepended to the URL path.
   Defaults to ``v0``. May also be controlled by setting environment
   variable: ``KUHA_DS_API_VERSION``.

.. option:: --document-store-client-request-timeout <timeout>

   Request timeout (in seconds) for Document Store client.
   Defaults to ``120``. May also be controlled by setting environment
   variable: ``KUHA_DOCUMENT_STORE_CLIENT_REQUEST_TIMEOUT``.

.. option:: --document-store-client-connect-timeout <timout>

   Connect timeout (in seconds) for Document Store client.
   Defaults to ``120``. May also be controlled by setting environment
   variable: ``KUHA_DOCUMENT_STORE_CLIENT_CONNECT_TIMEOUT``.

.. option:: --document-store-client-max-clients <max_clients>

   Maximum number of simultaneous client connections for Document Store client.
   Defaults to ``10``. May also be controlled by setting environment
   variable: ``KUHA_DOCUMENT_STORE_CLIENT_MAX_CLIENTS``.

.. 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``

.. option:: --logformat <logformat>

   Logging format supported by :mod:`logging`. Defaults to ``%(asctime)s %(levelname)s(%(name)s): %(message)s)``
   May also be controlled by setting environment variable: ``KUHA_LOGFORMAT``

**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_osmh_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_osmh_repo_handler_virtualenv.sh``.