Add docs for configuring and running basic (non-DB) app commands

docs/configure.rst

@@ -0,0 +1,139 @@
+
+.. 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.

docs/create-project.rst

@@ -201,3 +201,18 @@ And finally, at least in the case of this tutorial project, we wanted to go
 through and clean up some of the generated names, as well as assign authorship
 and project description etc. within the ``setup.py`` file.  (Then commit those
 changes and do another push, so we again have "clean" git status.)
+
+Installing Your Project
+-----------------------
+
+If you've just created a new project, technically we haven't yet shown how to
+"install" it within your virtualenv.  Here's how to do that::
+
+   pip install -e ~/src/poser
+
+Of course replace "poser" with your project's repo name there.
+
+This step is listed last within this section, to avoid the situation where you
+first install the project, then decide to change its name.  So ideally you
+should have settled on the name by now, and are happy with contents of
+``setup.py`` etc. before installing the project to your virtualenv.

docs/index.rst

@@ -54,6 +54,7 @@ Table of Contents
    setup-dev
    create-project
    start-docs
+   configure
 
 
 Indices and tables