Add docs for restoring from backup, esp. Borg archive

docs/backup/index.rst

@@ -23,3 +23,4 @@ existing Rattail app in charge of backups.
    config
    running
    features/index
+   restore

docs/backup/restore.rst

@@ -0,0 +1,159 @@
+
+.. highlight:: sh
+
+=======================
+ Restoring from Backup
+=======================
+
+Rattail tries to make the *backup* process more convenient, but it
+does *not* offer any conveniences for the *restore* process.
+
+However, it uses "standard" tools to create the backup, and each of
+those tools essentially provides a way to restore.  We'll briefly
+outline each and give links to further reading.
+
+
+Database Dumps
+==============
+
+If your backup was configured to include database dumps, that
+means you will have files generated by one or both of:
+
+* ``mysqldump`` (MySQL / MariaDB)
+* ``pg_dump`` (PostgreSQL)
+
+By default these files will be in the ``/root/data`` folder on the
+server (machine being backed up).  However if rsync/borg were used
+then copies of these files should be elsewhere as well, e.g. borg
+archives.
+
+Each is simply a gzip-ed SQL dump file as generated by the above
+commands.  See their docs for how to restore:
+
+* MariaDB: https://mariadb.com/kb/en/restoring-data-from-dump-files/
+* MySQL: https://dev.mysql.com/doc/mysql-backup-excerpt/8.0/en/reloading-sql-format-dumps.html
+* PostgreSQL: https://www.postgresql.org/docs/current/backup-dump.html#BACKUP-DUMP-RESTORE
+
+
+Rsync
+=====
+
+If your backup was configured to use ``rsync``, that just means that
+some files were copied "as-is" from your server (machine being backed
+up) to some target path.
+
+There is no default location for the target path, it will be whatever
+your config says.  Could be either a "local" path on the server, or
+some remote path accessed via SSH.
+
+Restoring such files is just a matter of copying them from that
+"target" path, back to wherever you need them to be..
+
+However note that the ``rsync`` method would normally only have the
+"most recent" copy of the files, which may not be sufficient for you
+to restore from, depending on the nature of the problem.  It's for
+this reason that you're encouraged to use the Borg feature also /
+instead.
+
+
+Borg
+====
+
+If your backup involves Borg then that typically means you have one or
+more target paths, to which Borg archives are written each night.  The
+archives are in fact written to a Borg "repo" which contains multiple
+archives, older ones being pruned over time to keep only so many
+around at a time.
+
+And again there may be more than one of these target paths (Borg
+repos).  From the perspective of the server (machine being backed up),
+there might be a Borg repo on an external disk, another on a local NAS
+device, another in a cloud server.  All of the repos though probably
+work the same and so you can restore from any the same.
+
+First, the official Borg docs on the matter:
+
+* https://borgbackup.readthedocs.io/en/stable/quickstart.html
+* https://borgbackup.readthedocs.io/en/stable/usage/mount.html
+
+
+Example Commands
+----------------
+
+For sake of example we'll show some commands to "mount" a Borg
+archive, at which point it looks just like another folder in your file
+system, and you can then copy files as you please.
+
+Let's assume that the Borg repo lives on an external drive attached to
+your server.  On your server then, we'll mount one of the archives.
+
+
+Command Basics
+~~~~~~~~~~~~~~
+
+Just a reminder here that you'll need the Borg encryption passphrase
+in order to decrypt the Borg repo and actually see "readable" files
+etc.  (Borg will prompt you for it.)  That password should be
+somewhere in ``/srv/envs/backup/app/rattail.conf`` on your server.
+
+Also note that all commands shown here are meant to run on your
+server, but *any* machine which has Borg installed, could be used for
+this.  You'd likely need to have SSH config in place in order to have
+basic access to the Borg repo location, and then would of course still
+need the encryption passphrase.
+
+
+List Borg Archives
+~~~~~~~~~~~~~~~~~~
+
+Next let's take a look at which archives are available, again assuming
+they're on an external drive (and assuming ``myserver`` is the name of
+your server)::
+
+   sudo -H borg list /mnt/external/borg-repos/myserver
+
+Note that if your Borg repo lives on another machine, then that
+command would look more like::
+
+   sudo -H borg list borg@cloud.example.com:/path/to/borg-repos/myserver
+
+
+Mount a Borg Archive
+~~~~~~~~~~~~~~~~~~~~
+
+Depending on which archives were listed via previous command, you
+would normally pick the one you wanted, and then "mount" it onto your
+local file system.
+
+First create a mount point just for this::
+
+   sudo mkdir -p /mnt/borg
+
+Then for instance, mount with something like::
+
+   sudo -H borg mount /mnt/external/borg-repos/myserver::myserver-2021-12-01T15:38:13 /mnt/borg
+
+And again if your Borg repo lives on another machine::
+
+   sudo -H borg mount borg@cloud.example.com:/path/to/borg-repos/myserver::myserver-2021-12-01T15:38:13 /mnt/borg
+
+Once mounted you can access the files just like you would any other
+mounted network share etc., the one caveat being that only root should
+have access to the borg mount.  For instance:
+
+.. code-block:: none
+
+   myuser@myserver:~$ sudo ls -l /mnt/borg
+   total 0
+   drwxr-xr-x 1 root root 0 Jun 25 19:31 etc
+   drwxr-xr-x 1 root root 0 Sep  8  2019 home
+   drwxr-xr-x 1 root root 0 Sep  8  2019 opt
+   drwx------ 1 root root 0 Jul 18  2020 root
+   drwxr-xr-x 1 root root 0 Sep  9  2019 srv
+   drwxr-xr-x 1 root root 0 Dec  1 21:35 usr
+   drwxr-xr-x 1 root root 0 Sep  8  2019 var
+
+
+When you're finished you should unmount::
+
+   sudo -H borg umount /mnt/borg