Add docs for rattail backup command

docs/backup/install.rst

@@ -0,0 +1,162 @@
+
+.. 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