Configuration

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:

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