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.