Generally batou tries to be very friendly when upgrading from version to version so you don’t have to unnecessarily change your deployments. We try to introduce new features without breaking existing semantics.

Upgrading to the separated appenv bootstrap file

appenv is a small, separate utility that batou uses to bootstrap and update itself, introduced in batou 2.

Initially we placed this file directly as ./batou but this turned out to be hard to deal with due to its “meta argument parser”. New versions of batou will automatically bootstrap this into two separate files: ./appenv and a symlink batou -> appenv.

To upgrade your project to this schema, follow those steps:

$ curl -sL https://raw.githubusercontent.com/flyingcircusio/batou/main/appenv.py -o appenv
$ chmod +x appenv
$ rm batou
$ ln -sf appenv batou

You can now use the appenv meta commands by calling the appenv utility itself:

$ ./appenv --help
usage: appenv [-h] {update-lockfile,init,reset,python,run} ...

positional arguments:
    update-lockfile     Update the lock file.
    init                Create a new appenv project.
    reset               Reset the environment.
    python              Spawn the embedded Python interpreter REPL
    run                 Run a script from the bin/ directory of the virtual env.

optional arguments:
  -h, --help            show this help message and exit

batou 1.x to batou 2.x

This upgrade mainly consists of a switch from Python 2 to Python 3 but it also does include a few details about how things are handled.

Major changes

  • batou requires at least Python 3.5, anything newer is fine, too.

  • File changes now show (expected) diffs.

  • You can deploy to multiple hosts at once using the -j option or the jobs option in the environment configuration.

  • Secrets can now also override data- sections for hosts.

  • You can now use assert instead of raise UpdateNeeded in the verify methods.

  • The embedded supervisor has been updated.

Updating your deployment

The following steps assume that you have cloned and checked out your deployment and it is your current working directory.

$ curl -sL https://raw.githubusercontent.com/flyingcircusio/batou/main/bootstrap | sh

The generated lockfile requirements.lock might not pick up all versions of all packages correctly (for example packages taken directly from source control will fail) so you might want to doublecheck those and massage the lockfile in case that this fails with something like:

ERROR: No matching distribution found for batou-ext==0.1.dev0 (from -r .batou/16f85f2d/requirements.lock (line 3))


batou_ext will be updated automatically to a proper Python 3 version and syntax.

At this point you can now update your projects’ component code to Python 3:

$ 2to3 -w components

After this you need to run batou in your development environment to see whether any further changes may be needed.

Things you may have to change in your deployment

  • Add sensitive_data=True to files that may contain sensitive data and whose content you do not want to see in any logs. This suppresses diff generation.

  • The default hash function has been changed to sha512 and thus existing hashes relying on the default being md5 will fail.

Updating to a newer batou 2.x version

After having switched from batou 1.x to 2.x you might update to the latest batou release once in a while. This requires the following steps:

  • Edit requirements.txt and enter the desired version: batou==2.x.

    • If you want to use an unreleased version use a git URL like this: -e git+https://github.com/flyingcircusio/batou.git#egg=batou instead of the batou==2.x requirement.

  • Run ./appenv update-lockfile to update requirements.lock.

  • Commit the changes and run batou so it can update itself to the new version.

Updating from 2.2 to 2.3

To define Attributes more explicitly the default value has to be passed in one of two ways.

  • default allows to pass a final python value or use a ConfigString value to trigger the conversion of the Attribute on a default value. This can be used for more concise code (e.g. Address) or for documentation of the format for environment.cfg. This way expand and map of the string will also be done.