rattail-tutorial/docs/configure.rst

.. highlight:: sh

Configure and Run Basic App
===========================

At this point you should have a virtual environment, and you either have
created a new project, or else have cloned the source for this rattail-tutorial
project.

But in either case we have yet to really *configure* anything, which needs to
be done before you can really run your app.  So we'll do those things now.


Setup the App Folder
--------------------

A typical Rattail-based app will have an "app" folder directly underneath the
virtual environment root folder.  Here is where we'll keep *all* files and
folders which are needed by the running app(s), e.g.:

* config files
* log files
* extra template files
* batch data files (input and/or output)
* file uploads from web app
* user session data for web app

And so on.  Really the goal here is for most "everything" which should be
included in an app "backup" to reside within this app folder, so that we may
simply backup the entire app folder.  (Note that this app folder does *not*
contain the project source code or installed packages; its focus is on config
and data rather than code proper.)

With your virtualenv activated, create this app folder like so::

   rattail make-appdir

.. note::
   For security in a production environment, you may wish to lock down
   permissions for some of the folders which are generated by that command.  We
   won't go over the details here but the recommendation is to run production
   apps as the "rattail" system user, in which case some app folders
   (e.g. ``app/log``) should perhaps be readable only by this rattail user.


Make/Edit Config Files
----------------------

Now that we have a proper app folder, we can put some config files in it.

Configuration is a tricky subject to document, since ultimately what you need
to configure will depend on the specifics of your app.  But we can generate a
few config files to use as a starting point::

   cdvirtualenv app
   rattail make-config -T rattail
   rattail make-config -T quiet
   rattail make-config -T web

Why all the config files?  Well, they can "inherit" from each other.  A quick
note about the "purpose" of each of those files:

``rattail.conf`` is considered the "core" config file for the app, which means
that no matter how you run the app, this file should be (in)directly referenced
somehow, so that it affects the runtime behavior.

``quiet.conf`` is meant to be used for ad-hoc app commands which you run from
the console.  It is a thin wrapper around ``rattail.conf`` and merely tries to
cut down on some of the output (logging) "noise" from commands.

``web.conf`` is meant to be used by the web app only.  It also inherits from
``rattail.conf`` though.

**Now the big chore is to go through all those files, looking for TODO notes
and such, and generally tweaking them to your liking.**

(You may notice there is config for a Rattail database in there; we'll deal
with that soon, but you can ignore it for the moment.)

Note that you are free to add additional config files as needed, for
convenience when running an app command in a particular "mode" (e.g. disable
some feature in certain situations).  Within this tutorial, we will eventually
add more config files for particular app features, e.g. datasync.

.. note::
   Again, for security in a production environment you often should make at
   least certain config files readable only by the runtime user, i.e. rattail.


Run the Basic App (No DB)
-------------------------

Before we establish a Postgres database for the app (or attempt to run the web
app), let's first get a feel for running ad-hoc commands via the console, which
do not require a database.

In fact we've already done a bit of that, using various ``rattail`` commands to
establish the app dir and initial config files.  But now let's try some
commands which actually use those config files.

.. note::
   Whereas above we used simply the ``rattail`` command, we from now on will
   generally be using the ``bin/rattail`` command instead.  The two are
   basically equivalent, but the latter assumes only that your current working
   directory is your virtualenv root, so technically you may not need to have
   your virtualenv *activated* (which can be convenient sometimes).

We'll keep this fairly short and sweet though.  First let's see what commands
Rattail comes with out of the box::

   cdvirtualenv
   bin/rattail --help

Okay, not bad, now let's generate a new UUID with::

   bin/rattail make-uuid

That should just spit out a UUID with no bells or whistles.  Now let's try the
same thing, but this time we'll specify our app's ``rattail.conf`` config
file::

   bin/rattail -c app/rattail.conf make-uuid

Well that was sure a little different, but not for the better is what you're
probably thinking.  As you can see the ``rattail.conf`` file defines some
logging config, whereas the first command didn't have any of that.

Let's try that command once more but this time use ``quiet.conf`` instead::

   bin/rattail -c app/quiet.conf make-uuid

That's better!  This time we *do* have logging configured, so e.g. you can
still find those details in ``app/log/rattail.log``, but we have suppressed
"most" of the logging output on the console.

As noted previously, ``quiet.conf`` is designed for exactly this purpose.
However it should also be pointed out, that "quiet" does not mean "silent" -
this config will suppress most logging noise, but not all.