.. highlight:: sh

==============
 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
:doc:`/deploy/index` and the ``rattail_fabric2.backup`` module for
more info.  That (rattail-fabric2) package is available on PyPI, or
can peek at the `module source`_.

.. _module source: https://kallithea.rattailproject.org/rattail-project/rattail-fabric2/files/master/rattail_fabric2/backup.py

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.

* :doc:`/base/reqs`
* :doc:`/base/venv`
* :doc:`/base/install/index`

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 :doc:`config`.  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