Configuration
=============

The main configuration of Fietsboek is done via ``.ini``-files. By default,
three such files exist:

* ``production.ini`` contains the configuration for the production environment.
  It turns off debugging features (as they are a security risk!) and should
  contain the URL of the production database. This is the main file you want to
  use if you just want to deploy Fietsboek.
* ``development.ini`` contains the configuration for local development on
  Fietsboek. **This should not be used for production purposes, as it provides
  debugging information that poses a security risk!**
* ``testing.ini`` contains the configuration that the automated tests will use.

Most of the configuration is in the ``[app:main]`` category and looks like this:

.. code:: ini

    [app:main]
    use = egg:fietsboek

    pyramid.reload_templates = false
    pyramid.debug_authorization = false
    pyramid.debug_notfound = false
    pyramid.debug_routematch = false
    pyramid.default_locale_name = en

    email.from = fietsboek@kingdread.de
    email.smtp_url = debug://localhost:1025

    available_locales = en de
    enable_account_registration = true

    session_key = <EDIT THIS>

    sqlalchemy.url = sqlite:///%(here)s/fietsboek.sqlite
    fietsboek.data_dir = %(here)s/data

    retry.attempts = 3

* You should leave the ``use``, ``pyramid.reload_templates`` and
  ``pyramid.debug_*`` settings as they are.
* ``pyramid.default_locale_name`` can be used to set the default language of
  the installation. Note that Fietsboek will try to detect the user's language,
  so the ``default_locale_name`` is used as a fallback.
* ``available_locales`` sets the list of available languages. Currently,
  Fietsboek ships with English ("en") and German ("de"). Removing a language
  from this list will make it unavailable. If you create a custom language
  locally, make sure to add it to this list here!
* ``enable_account_registration`` can be used to enable and disable the
  creation of new accounts via the web interface, for example if you want to
  have a private instance. New accounts can always be created using the CLI
  management tool.
* ``session_key`` should be set to a random string of characters. This is the
  key used to sign session data, so it should not get into wrong hands!
* ``sqlalchemy.url`` is the URL to the database. See the `SQLAlchemy
  documentation
  <https://docs.sqlalchemy.org/en/14/core/engines.html#database-urls>`__ for
  more information.
* ``fietsboek.data_dir`` sets the directory for data uploads. This directory
  must be writable by the Fietsboek process, as Fietsboek will save track
  images in there.
* ``email.from`` sets the sender of emails, for example for account verifications.
* ``email.smtp_url`` sets the URL of the SMTP server. The following formats are accepted:

  * ``debug://`` a debug implementation that simply prints emails to the
    standard output. Should not be used in production, as no emails would ever
    arrive.
  * ``smtp://host:port`` use the given SMTP server (without transport encryption!)
  * ``smtp+ssl://host:port`` use the given SMTP server over a SSL connection
  * ``smtp+starttls://host:port`` use the given SMTP server and the STARTTLS
    command to start an encrypted channel.

* ``email.username`` and ``email.password`` can be used to set the login
  information for the SMTP server.
* ``thunderforest.api_key`` can be set to an API key of `Thunderforest
  <https://www.thunderforest.com/>`__ to enable support for the OpenCycleMap,
  Landscape and Outdoors maps.

.. warning::

    The API key will be embedded in the source of the website, therefore it is
    possible for visitors to "steal" the API key. Keep that in mind when
    setting an API key for a publicly accessible site!