From a428bebda9012fc07d502f7960e00373c908364f Mon Sep 17 00:00:00 2001 From: Lance Edgar Date: Mon, 22 Jan 2018 16:30:09 -0600 Subject: [PATCH] Add basic "config" concept doc --- docs/concepts/config.rst | 110 +++++++++++++++++++++++++++++++++++++- docs/concepts/console.rst | 7 +++ docs/index.rst | 2 + 3 files changed, 118 insertions(+), 1 deletion(-) create mode 100644 docs/concepts/console.rst diff --git a/docs/concepts/config.rst b/docs/concepts/config.rst index d20aa723..9d7eacb3 100644 --- a/docs/concepts/config.rst +++ b/docs/concepts/config.rst @@ -4,4 +4,112 @@ Configuration .. contents:: :local: -TODO +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. diff --git a/docs/concepts/console.rst b/docs/concepts/console.rst new file mode 100644 index 00000000..32912d6a --- /dev/null +++ b/docs/concepts/console.rst @@ -0,0 +1,7 @@ + +Console Commands +================ + +.. contents:: :local: + +TODO diff --git a/docs/index.rst b/docs/index.rst index 6f95b883..e547fb4e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -27,6 +27,8 @@ Concept Guide: .. toctree:: concepts/config + .. + concepts/console concepts/schema concepts/batches