System Admin Playbook

While pyApp offers a lot of features to help developers be more productive, it also provides a suite of tools for Sysadmins to help identify application issues and simplify operation of an application developed with pyApp.


pyApp provides a CLI that provides a --help option at most locations, this is a great way to find out more about a command or what commands are available.

All builtin commands include help using this method.


The recommended approach to deploy a pyApp application is using a virtual environment (virtualenv or venv) or within a container (eg Docker). This keeps your application self contained with only the expected dependencies installed.

pyApp uses automatic extension loading to get the default configuration loaded and by using a container only the expected extensions will be available and loaded.


By default pyApp configures logging to be directed to stderr and any report output (of builtin tools) to be directed to stdout, this allows for application output to be piped to other tools or files.

Exit Codes

pyApp has a top level exception handler that will put a stacktrace of any unhandled exceptions into the log before passing the exception onto Pythons standard mechanisms.

Keyboard Interruptions (Ctrl+C) are caught and will return -2.

A normal exit will generate the standard 0 exit code.

Run-time Settings

Settings can be supplied at run time to provide environmental specific configuration or to just change the behaviour of an application for testing. This can be done via two methods:

  1. Using the --settings command line argument eg:

    > my_application --settings production_settings
  2. Using an Environment variable. The environment variable defaults to PYAPP_SETTINGS, however, this can be changed by the development team to prevent naming clashes, the correct value is always reported when using the --help option.

Both of these options can be used at the same time, environment variables is particularly useful in a Docker container.

Runtime settings can be defined in a number of ways:

  • A python module

  • A local JSON or YAML file

  • A remote JSON or YAML file via HTTP(S)

See the Conf.Loaders section of the Reference guide for information on loading different settings files.

Run-Time Checks

pyApp includes a checks framework designed for running environmental checks to confirm that configuration is valid, services can be accessed (eg Databases, External Hosts, SSH). This lets the application be verified quickly without running any business processes.

To run the checks use:

> my_application checks

# With more detail

> my_application checks --verbose

How do I

Common operations that need to performed by an operations team and how to do them.

How do I change the log level?

The log level can be changed by either:

  1. Using the --log-level option on the command line

  2. Setting the PYAPP_LOGLEVEL environment variable


The log-level environment variable can be renamed, use the --help option to get the current name.

What are the current settings?

What is the applications current configuration and what values are being used:

> my_application settings

This command will list all of the current application settings, the log will indicate what settings files are being loaded.

Where are the settings being loaded from?

Using the settings command combined with DEBUG level logging reports not only what settings file are being loaded, but each individual value from each file:

> my_application --log-level DEBUG settings

What extensions are being loaded with the application?

All extensions that are available (without actually loading them) along with their version can be obtained using the builtin extensions command:

> my_application extensions

How do I perform a PIV (Post Implementation Verification) test?

The checks framework can provide the basis of a PIV test prior to running any processes, this ensures the environment and any connectivity problems can be identified before longer more complex processes are started.

How do I perform regular monitoring checks?

The checks framework can be used to perform regular monitoring of the application via a cron job. To simplify making use of this data the checks report has a tabular output that can be processed as a Tab Separated output for easy parsing:

> my_application checks --table