Installation

As usual there is more than one way to go about this. You basically have these 2 options out of the gate:

  • manual install

  • scripted install via Fabric

Choice is yours. If you are interested in Fabric, see Deployment Layer and the rattail_fabric2.backup module for more info. That (rattail-fabric2) package is available on PyPI, or can peek at the module source.

Here we will only describe the manual installation.

The following links offer more background should you want it. But we’ll provide the basic commands you need, further below.

Note also, the steps below are “established convention” so to speak, but only in the Rattail world. If you follow along exactly then things should work, but you of course can tweak as needed.

Virtual Environment

If you don’t already have one, make a home for virtual environments.

Note that we assume this folder should be owned by the rattail user account. If you don’t have that, specify a different owner:

sudo mkdir -p /srv/envs
sudo chown rattail: /srv/envs

Then make your backup virtual environment:

sudo -u rattail python3 -m venv /srv/envs/backup

Backup App

Install the Rattail package to the virtual environment. Note that we specify rattail[backup] which causes it to also install Borg:

cd /srv/envs/backup
sudo -u rattail bin/pip install rattail[backup]

You can just use pip install rattail instead if you do not want Borg.

We then invoke Rattail to create our app folder, which is where config will live:

cd /srv/envs/backup
sudo -u rattail bin/rattail make-appdir

And that’s it for the software, unless you also want rsync:

sudo apt install rsync

Backup Scripts

It is suggested that you also create the following scripts, for convenience.

Note that these scripts will not work properly until you add config files; see Configuration. But it’s fine to get the scripts in place first since they probably won’t need to change later on.

Note also that these scripts are designed to be ran only by the root user. They will warn and not take action, when ran by anyone else.

Script: rattail-backup

The purpose of this script is simply to wrap the underlying rattail backup command, specifying the appropriate config file etc. Any arguments you pass to it will be passed on to the command.

Instead of listing the contents of this file here, we will direct you to the “official” copy which can be deployed via Fabric:

https://kallithea.rattailproject.org/rattail-project/rattail-fabric2/rawfile/master/rattail_fabric2/deploy/backup/rattail-backup.mako

You will need to (globally) replace the text ${envname} with backup but otherwise that can be used as-is.

Place this file at /usr/local/bin/rattail-backup and make it executable:

sudo chmod 0755 /usr/local/bin/rattail-backup

Run it like so; note that --help is not interpreted by the script but rather is passed on to the underlying command:

sudo -H rattail-backup --help

If you were to run the “same” command but without the wrapper script, it would look like:

cd /srv/envs/backup
sudo -H bin/rattail -c app/rattail.conf backup --help

Script: backup-everything

The purpose of this script is to give the admin user a single “entry point” for running backups on “all” machines regardless of their configuration details.

Really the rattail-backup script could be used for this too, but backup-everything just has a more authoritative sound to it.

Again instead of listing the file contents we will direct you to the “official” copy which can be deployed via Fabric:

https://kallithea.rattailproject.org/rattail-project/rattail-fabric2/rawfile/master/rattail_fabric2/deploy/backup/backup-everything.mako

Again you will need to (globally) replace the text ${envname} with backup but you also should comment-out the line which tries to invoke app/upgrade.sh (unless you have that and want to use it).

Place this file at /usr/local/bin/backup-everything and make it executable:

sudo chmod 0755 /usr/local/bin/backup-everything

This script also wraps the underlying rattail backup command. Note that it does not wrap the rattail-backup script (from previous section).

Really unless you modify this script, it will just run the rattail backup command, again with the appropriate config file, but without any other arguments, so any extra ones you specify will not be passed on to the underlying command.

Run it like so; note that it only takes one optional argument, --verbose:

sudo -H backup-everything [--verbose]

If you were to run the “same” command but without the wrapper script, it would look like:

cd /srv/envs/backup
sudo -H bin/rattail -c app/rattail.conf backup