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.