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