140 lines
5.3 KiB
ReStructuredText
140 lines
5.3 KiB
ReStructuredText
|
|
.. 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.
|