Add docs for rattail backup command

docs/backup/features/borg.rst

@@ -0,0 +1,100 @@
+
+.. highlight:: ini
+
+======
+ Borg
+======
+
+Rattail can invoke the ``borg create`` command, to make one or more
+Borg archives at configured locations.  For more about Borg, see
+`<https://www.borgbackup.org/>`_.
+
+This allows for multiple destinations so that to be extra super safe,
+you can e.g. make archives at each of:
+
+* second drive attached to local machine
+* path on remote machine on local network
+* path on remote machine in the cloud
+
+Rattail also will invoke the ``borg prune`` command to keep the
+archive repositories from growing too large etc.
+
+
+Configuration
+=============
+
+You can enable the borg feature like so::
+
+   [rattail.backup]
+   borg.enabled = true
+
+The borg feature is *disabled* by default but you can make that
+explicit::
+
+   [rattail.backup]
+   borg.enabled = false
+
+
+Destination(s)
+--------------
+
+Rattail supports multiple destinations for Borg archives; it will run
+``borg create`` (and also ``borg prune``) separately for each defined.
+
+As an example we'll show config with 3 destinations; hopefully from
+here you can figure out how to do what you need::
+
+   [rattail.backup]
+   borg.remotes = 
+      mydrive
+      otherserver
+      cloudserver
+
+   borg.remote.mydrive.repo = /mnt/mydrive/borg-storage/myserver
+   borg.remote.mydrive.passphrase = sooperseekrit
+
+   borg.remote.otherserver.repo = borguser@otherserver:/srv/borg-storage/myserver
+   borg.remote.otherserver.passphrase = sooperseekrit
+
+   borg.remote.cloudserver.repo = borguser@cloudserver:/srv/borg-storage/myserver
+   borg.remote.cloudserver.passphrase = sooperseekrit
+
+The above uses the same Borg encryption passphrase for all 3
+repositories but they could be different if you wanted.
+
+If destination is on another server, in some cases you must tell
+Rattail where the Borg binary lives on that server, e.g.::
+
+   [rattail.backup]
+   borg.remotes = cloudserver
+
+   borg.remote.cloudserver.repo = borguser@cloudserver:/srv/borg-storage/myserver
+   borg.remote.cloudserver.passphrase = sooperseekrit
+   borg.remote.cloudserver.borg = /path/to/borg
+
+
+Files to Backup
+---------------
+
+This works the same way as for rsync; see
+:ref:`rsync-include-exclude`.
+
+However the actual config option names can vary in the following way:
+
+If you prefer, or need to differentiate, you can specify the include
+and exclude options with ``borg`` prefix::
+
+   [rattail.backup]
+   borg.include = /home
+   borg.exclude = /home/ignoreme
+
+If you do specify them that way, Rattail will honor them.  But if you
+do not, it also will honor the same options with ``rsync`` prefix::
+
+   [rattail.backup]
+   rsync.include = /home
+   rsync.exclude = /home/ignoreme
+
+This is because anyone using both rsync *and* borg will likely want
+the same set of files backed up both ways.  Also because the rsync
+feature came first...

docs/backup/features/dbdump.rst

@@ -0,0 +1,63 @@
+
+.. highlight:: ini
+
+================
+ Database Dumps
+================
+
+Rattail can dump all of your databases to file so that they can be
+included in the filesystem backup that happens via ``rsync`` and/or
+``borg create``.
+
+It only supports PostgreSQL and MySQL/MariaDB but those should work
+out of the box.  It will figure out which databases are present, then
+dump each to its own file.  Note that it puts them all in the
+``/root/data`` folder by default.
+
+
+Configuration
+=============
+
+You can enable the database dump feature like so::
+
+   [rattail.backup]
+   dbdump = true
+
+Note that the dbdump feature is *enabled* by default; you can disable
+like so::
+
+   [rattail.backup]
+   dbdump = false
+
+If you don't like ``/root/data`` then you can change output folder::
+
+   [rattail.backup]
+   dbdump.output = /my/preferred/folder
+
+Exclude certain databases which you do not need backed up (note, it
+does not matter if these live in PostgreSQL or MySQL, Rattail will
+just ignore these regardless where they're found)::
+
+   [rattail.backup]
+   dbdump.exclude = mytestdb, anotherdb
+
+Alternate syntax for that, useful for longer lists::
+
+   [rattail.backup]
+   dbdump.exclude = 
+       mytestdb
+       anotherdb
+
+Or, *only* include certain databases and exclude all others::
+
+   [rattail.backup]
+   dbdump.include = 
+      importantdb
+      anotherdb
+
+If you want, Rattail can dump *all* tables individually as well as
+dumping the databases themselves.  Each database file will be
+accompanied by a folder which will contain the table files::
+
+   [rattail.backup]
+   dbdump.dump_tables = true

docs/backup/features/index.rst

@@ -0,0 +1,22 @@
+
+==========
+ Features
+==========
+
+As mentioned earlier, Rattail's backup logic can do the following:
+
+* dump databases to file
+* run ``rsync`` to copy files somewhere
+* run ``borg create`` to make Borg archive(s) somewhere
+
+Note that the database dump always happens first, so that the
+resulting files can be included in the ``rsync`` or ``borg create``
+runs (if applicable).
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents:
+
+   dbdump
+   rsync
+   borg

docs/backup/features/rsync.rst

@@ -0,0 +1,95 @@
+
+.. highlight:: ini
+
+=======
+ Rsync
+=======
+
+Rattail can invoke the ``rsync`` command to copy relevant portions of
+the file system to another location.
+
+The main disadvantage to rsync is that the "backup" is competely
+replaced every time the command runs.  So you always have just one
+"most recent" backup.
+
+Doing so is almost certainly better than nothing, but Borg is really a
+superior solution in every way it seems.  You are encouraged to use
+that instead.
+
+
+Configuration
+=============
+
+You can enable the rsync feature like so::
+
+   [rattail.backup]
+   rsync = true
+
+The rsync feature is *disabled* by default but you can make that
+explicit::
+
+   [rattail.backup]
+   rsync = false
+
+By default Rattail will run ``rsync`` before it runs ``borg create``,
+but you can reverse that sequence if you need to::
+
+   [rattail.backup]
+   rsync.last = true
+
+
+Destination
+-----------
+
+Rattail only supports a single "destination" for rsync.  This can be
+either a "local" path, e.g. a backup drive mounted to the main
+filesystem, or can be a remote path accessible via SSH.
+
+Here is what a "local" path would look like, e.g. if we want rsync to
+write files in the ``/mnt/mydrive/server-backup`` folder::
+
+   [rattail.backup]
+   rsync.remote_prefix = /mnt/mydrive/server-backup
+
+And if we instead wanted rsync to write to the ``/srv/server-backup``
+folder on the ``otherserver`` remote machine::
+
+   [rattail.backup]
+   rsync.remote_host = otherserver
+   rsync.remote_prefix = /srv/server-backup
+
+
+.. _rsync-include-exclude:
+
+Files to Backup
+---------------
+
+Rattail will by default only include certain folders in the rsync run,
+and avoid things like the ``/tmp`` folder etc.  You can override this
+as needed, but here is the default list of what it includes::
+
+   [rattail.backup]
+   rsync.include = 
+       /etc
+       /home
+       /opt
+       /root
+       /srv
+       /usr/local
+       /var
+
+Rattail will also exclude some things by default; again override as
+needed but here is that default list.  Note that the convention used
+is to specify trailing slash for folders, and not for files.  These
+values are passed directly to the ``rsync`` command so ultimately it
+will be interpreting them::
+
+   [rattail.backup]
+   rsync.exclude = 
+       /var/cache/
+
+Note that it is only necessary to *exclude* things which fall "within"
+folders which are *included* ..e.g. no reason to explicitly exclude
+the ``/tmp`` folder since it wasn't included.  But since ``/var`` is
+included we must exclude ``/var/cache`` or else it would be backed up
+along with the rest.