App Folder

Here we describe the “app folder” (aka. “app dir”), for instance at /srv/envs/poser/app, which contains all config and data for the app.

Rationale

We’ll use a typical Linux example here. Let’s say we have a “poser” virtual environment in the default location. By default the folder structure within the virtual environment may look something like this:

/srv/envs/poser
├── bin
├── include
├── lib
│   └── python3.8
├── man
└── share

Once the Python package(s) for our app have been installed to the virtual environment, we will create an “app” folder in the environment root. This app folder will contain all config, data and log files for the app.

The idea here is that a proper (minimal) backup for the app, should only require this “app dir” but the other virtual environment folders need not be included in the backup (although they still can be, of course).

Making the App Dir

This may be done with or without activating your virtual environment.

If your env is activated:

rattail make-appdir

If your env is not activated:

cd /srv/envs/poser
bin/rattail make-appdir

Structure

Keep in mind that the following is just an example. Each app is unique and many of the folders described below can live elsewhere as long as the app is configured appropriately. But this example is “typical” so its conventions should be used unless there is a good reason not to.

For the sake of completeness here we will assume a fairly robust app, which uses several possible features and has been running a while. Here is what the final virtual environment may look like:

/srv/envs/poser
├── app
│   ├── data
│   │   ├── batches
│   │   │   ├── inventory
│   │   │   ├── vendor_catalog
│   │   │   └── vendor_invoice
│   │   ├── exports
│   │   │   ├── instacart_product_export
│   │   │   └── report_output
│   │   ├── templates
│   │   ├── upgrades
│   │   └── uploads
│   ├── log
│   ├── luigi
│   │   ├── 2020
│   │   ├── 2021
│   │   └── log
│   ├── luigitasks
│   ├── sessions
│   │   ├── data
│   │   └── lock
│   └── work
│       ├── csv
│       ├── generated-projects
│       └── user-files
├── bin
├── include
├── lib
│   └── python3.8
├── man
└── share

First you may note that the above does not include a “config” folder. All config files, and most scripts, will generally live directly within the “app” folder itself.

And now for a rundown of the “important” folders you do see above:

app/data ideally contains all “true” data for the app. What we mean by that is, any data which the app requires to be 100% fully functional. Much of this data is generated by the app itself, but should remain available for later display within the app.

app/data/batches contains all data files used as input, or generated as output, for various “batches” within the app.

app/data/exports contains all “export” files generated by the app, e.g. when certain reports are ran etc.

app/data/templates may contain certain template files needed by the app when it is generating various kinds of output.

app/data/upgrades contains the before and after package snapshots, and command output etc. when an app upgrade is executed.

app/data/uploads is more of a temp folder, used to store files uploaded by a user within the web app, until they are further processed.

app/log is where all log files go for the app proper.

app/luigi is where Luigi (if used) will keep track of which individual tasks have already been ran for a given date.

app/luigi/log will contain log files for both the Luigi server and client.

app/luigitasks contains the task logic to be ran by Luigi.

app/sessions contains the “user session” data for the web app(s).

app/work is more of a temp folder; its contents may vary over time and are not considered essential to the app.