tailbone/docs/concepts/config.rst

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

.. contents:: :local:

Configuration for an app can come from two sources: configuration file(s), and
the Settings table in the database.


Config File Inheritance
-----------------------

An important thing to understand regarding Rattail config files, is that one
file may "include" another file(s), which in turn may "include" others etc.
Invocation of the app will often require only a single config file to be
specified, since that file may include others as needed.

For example ``web.conf`` will typically include ``rattail.conf`` but the web
app need only be invoked with ``web.conf`` - config from both files will inform
the app's behavior.


Typical Config Files
--------------------

A typical Poser (Rattail-based) app will have at the very least, one file named
``rattail.conf`` - this is considered the most fundamental config file.  It
will usually define database connections, logging config, and any other "core"
things which would be required for any invocation of the app, regardless of the
environment (e.g. console vs. web).

Note that even ``rattail.conf`` is free to include other files.  This may be
useful for instance, if you have a single site-wide config file which is shared
among all Rattail apps.

There is no *strict* requirement for having a ``rattail.conf`` file, but these
docs will assume its presence.  Here are some other typical files, which the
docs also may reference occasionally:

**web.conf** - This is the "core" config file for the web app, although it
still includes the ``rattail.conf`` file.  In production (running on Apache
etc.) it is specified within the WSGI module which is responsible for
instantiating the web app.  When running the development server, it is
specified via command line.

**quiet.conf** - This is a slight wrapper around ``rattail.conf`` for the sake
of a "quieter" console, when running app commands via console.  It may be used
in place of ``rattail.conf`` - i.e. you would specify ``-c quiet.conf`` when
running the command.  The only function of this wrapper is to set the level to
INFO for the console logging handler.  In practice this hides DEBUG logging
messages which are shown by default when using ``rattail.conf`` as the app
config file.

**cron.conf** - Another wrapper around ``rattail.conf`` which suppresses
logging even further.  The idea is that this config file would be used by cron
jobs; that way the only actual output is warnings and errors, hence cron would
not send email unless something actually went wrong.  It may be used in place
of ``rattail.conf`` - i.e. you would specify ``-c cron.conf`` when running the
command.  The only function of this wrapper is to set the level to WARNING for
the console logging handler.

**ignore-changes.conf** - This file is only relevant if your ``rattail.conf``
says to "record changes" when write activity occurs in the database(s).  Note
that this file does *not* include ``rattail.conf`` because it is meant to be
supplemental only.  For instance on the command line, you would need to specify
two config files, first ``rattail.conf`` or a suitable alternative, but then
``ignore-changes.conf`` also.  If specified, this file will cause changes to be
ignored, i.e. **not recorded** when write activity occurs.

**without-versioning.conf** - This file is only relevant if your
``rattail.conf`` says to enable "data versioning" when write activity occurs in
the database(s).  Note that this file does *not* include ``rattail.conf``
because it is meant to be supplemental only.  For instance on the command line,
you would need to specify two config files, first ``rattail.conf`` or a
suitable alternative, but then ``without-versioning.conf`` also.  If specified,
this file will disable the data versioning system entirely.  Note that if
versioning is undesirable for a given app run, this is the only way to
effectively disable it; once loaded that feature cannot be disabled.


Settings from Database
----------------------

The other (often more convenient) source of app configuration is the Settings
table within the app database.  Whether or not this table is a valid source for
app configuration, ultimately depends on what the config file(s) has to say
about it.

Assuming the config file(s) defines a database connection and declares it a
valid source for config values, then the Settings table may contribute to the
running app config.  The nice thing about this is that these settings are
checked in real-time.  So whereas changing a config file will require an app
restart, any edits to the settings table should take effect immediately.

Usually the settings table will *override* values found in the config file.
This behavior also is configurable to some extent, and in some cases a config
value may *only* come from a config file and never the settings table.

An example may help here.  If the config file contained the following value:

.. code-block:: ini

   [poser]
   foo = bar

Then you could create a new Setting in the database with the following fields:

* **name** = poser.foo
* **value** = baz

Assuming typical setup, i.e. where settings table may override config file, the
app would consider 'baz' to be the config value.  So basically the setting name
must correspond to a combination of the config file "section" name, then a dot,
then the "option" name.