Add docs for rattail backup command

2021-10-31 21:18:04 -05:00 · 2021-10-31 21:18:04 -05:00 · 25d1c1b739
commit 25d1c1b739
parent 47fb1e451a
10 changed files with 667 additions and 7 deletions
--- a/docs/backup/config.rst
+++ b/docs/backup/config.rst
@ -0,0 +1,149 @@
+
+.. highlight:: ini
+
+===============
+ Configuration
+===============
+
+The backup "app" you have installed is really just Rattail proper, so
+the config we will describe adheres to normal Rattail conventions.
+See :doc:`/base/config/index` for more background on that.
+
+We put all pertinent config in one file at
+``/srv/envs/backup/app/rattail.conf`` and this will control behavior
+of the ``rattail backup`` command.
+
+
+Config File: ``rattail.conf``
+=============================
+
+This is the primary config file for the backup app.  Out of necessity
+it will vary for different people and the different machines they need
+to backup.  As such there is no "official" copy to be deployed by
+Fabric.
+
+So create the file at ``/srv/envs/backup/app/rattail.conf`` and in it
+put these contents as your starting point::
+
+   ############################################################
+   #
+   # config for backups
+   #
+   ############################################################
+
+
+   ##############################
+   # rattail
+   ##############################
+
+   [rattail]
+   timezone.default = America/Chicago
+
+   [rattail.config]
+   configure_logging = true
+
+   [rattail.backup]
+   dbdump = true
+   rsync = false
+   borg.enabled = false
+
+
+   ##############################
+   # logging
+   ##############################
+
+   [loggers]
+   keys = root
+
+   [handlers]
+   keys = file, console
+
+   [formatters]
+   keys = generic, console
+
+   [logger_root]
+   handlers = file, console
+   level = DEBUG
+
+   [handler_file]
+   class = handlers.RotatingFileHandler
+   args = ('/srv/envs/backup/app/log/rattail.log', 'a', 1000000, 20, 'utf_8')
+   formatter = generic
+
+   [handler_console]
+   class = StreamHandler
+   args = (sys.stderr,)
+   formatter = console
+
+   [formatter_generic]
+   format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(funcName)s: %(message)s
+   datefmt = %Y-%m-%d %H:%M:%S
+
+   [formatter_console]
+   format = %(levelname)-5.5s [%(name)s][%(threadName)s] %(funcName)s: %(message)s
+
+.. caution::
+   It is a good idea to "lock down" this file.  There are no secrets
+   (passwords etc.) in the example above, but it's possible you may
+   need to add them in the future, e.g. Borg encryption passphrase.
+   So it's recommended that you go ahead and lock this down now:
+
+   .. code-block:: sh
+
+      sudo chown rattail: /srv/envs/backup/app/rattail.conf
+      sudo chmod 0600 /srv/envs/backup/app/rattail.conf
+
+The above config file says the following:
+
+* declares local time zone to be ``America/Chicago``
+* tells Rattail that it should configure logging
+
+  * logging should be written to file at ``/srv/envs/backup/app/log/rattail.log``
+  * log file should be rotated when it reaches ~1MB
+  * logging also should go to console
+
+* when ``rattail backup`` runs, it should:
+
+  * dump all databases to file (for postgres and mysql)
+  * do *not* run ``rsync``
+  * do *not* run ``borg create``
+
+Later on we'll describe how to enable more features etc.  But it's
+recommended to follow along in order, and get the basics working
+first.
+
+
+Config File: ``silent.conf``
+============================
+
+The convention is to make ``rattail.conf`` specify ``DEBUG`` as the
+main log level, not only for logging to file but also to console.  For
+instance that is what the above example does.
+
+So the convention also is to add a ``silent.conf`` file which
+suppresses "normal" noise for the console logging.  Warnings and
+errors will still make it through, so "silent" does not mean "silent
+failure" - just "no ambient noise".
+
+Rattail can create this file for you:
+
+.. code-block:: sh
+
+   cd /srv/envs/backup
+   sudo -u rattail bin/rattail -c app/rattail.conf make-config -T silent -O app
+
+After that you can specify ``app/silent.conf`` for your commands when
+you want them to be "silent" - e.g. when running overnight:
+
+.. code-block:: sh
+
+   cd /srv/envs/backup
+   sudo -u rattail bin/rattail -c app/silent.conf backup --help
+
+Note that ``silent.conf`` inherits from ``rattail.conf`` so all config
+from that file will still be in effect.
+
+.. note::
+   When you run e.g. the default ``backup-everything`` script, if you
+   pass the ``--verbose`` flag then it will use ``rattail.conf`` but
+   if you do not then it will use ``silent.conf`` instead.