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.