Overhaul docs for Windows filemon install

sheesh, hopefully this is "most" of it..although definitely still not
all we need yet..

docs/base/install/windows/filemon/config/basic.rst

@@ -0,0 +1,198 @@
+
+.. highlight:: ini
+
+===========================
+ Basic, aka. "Starter Kit"
+===========================
+
+The purpose of this section is to provide you with a *simple*
+configuration which should be more or less guaranteed to work out of
+the box.
+
+It is suggested that you use this as-is when first installing, in
+order to rule out any "esoteric" issues that can arise from more
+complicated setups.  Once you have this working you can further
+complicate as needed.
+
+
+Config Folder
+-------------
+
+First things first, we need a place for config to live.  As mentioned
+in :doc:`overview` the filemon will only look in one place, so we must
+create this folder: ``C:\ProgramData\rattail``
+
+Note that ``C:\ProgramData`` is a hidden folder, so you may need to
+tweak options in Windows Explorer to see it.
+
+Note that the ``rattail`` user (or whoever the service runs as; see
+:doc:`/base/install/windows/user`) will definitely need "read" access
+to the folder you just created.  It probably has it by default but is
+worth a double-check.
+
+
+Log Folder
+----------
+
+Once we get the filemon running, we should expect it to write a log
+file.  So create the folder for that:  ``C:\ProgramData\rattail\log``
+
+Note that the ``rattail`` user will need read *and* write access to
+that folder; you may need to grant the latter.
+
+
+Testing Folders
+---------------
+
+Before we add our config files let's setup some folders which we will
+(eventually) test actual filemon behavior with.
+
+The basic config will tell filemon to do the following:
+
+* watch ``C:\rattail-test\incoming`` for new files
+* when they appear, move them to ``C:\rattail-test\incoming\processed``
+
+So create the folders:
+
+* ``C:\rattail-test\incoming``
+* ``C:\rattail-test\incoming\processed``
+
+And make sure the ``rattail`` user has read *and* write access to
+them.
+
+
+Config File: ``rattail.conf``
+-----------------------------
+
+This is the "machine-wide" config file (see
+:ref:`machine-wide-config`).  It should contain any "global" things
+which might be useful for any Rattail app running on the machine.
+(Even though in practice you probably only use the filemon app.)
+
+Note that in production it is suggested to use a "site-wide" config
+file which contains most of the global things, so they can be kept in
+just one place (see :doc:`variations`).  But for now we will ignore
+that and just make our ``rattail.conf`` "complete" on its own.
+
+So, create the file ``C:\ProgramData\rattail\rattail.conf`` and in it
+put this, perhaps tweaking timezone if desired but ideally leaving
+everything else as-is::
+
+   ############################################################
+   #
+   # machine-wide rattail config
+   #
+   ############################################################
+
+
+   ##############################
+   # rattail
+   ##############################
+
+   [rattail]
+   timezone.default = America/Chicago
+
+   [rattail.config]
+   configure_logging = true
+   winsvc.RattailFileMonitor = C:\ProgramData\rattail\filemon.conf
+
+
+   ##############################
+   # 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 = (r'C:\ProgramData\rattail\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
+
+Of course the ``rattail`` user must have read access to this file, so
+you might double-check that.
+
+
+Config File: ``filemon.conf``
+-----------------------------
+
+We will give the filemon service its own config file
+(``filemon.conf``), to avoid cluttering the machine-wide
+``rattail.conf`` file etc.
+
+So, create the file ``C:\ProgramData\rattail\filemon.conf`` and in it
+put this::
+
+   ############################################################
+   #
+   # filemon config
+   #
+   ############################################################
+
+
+   ##############################
+   # rattail
+   ##############################
+
+   [rattail.config]
+   include = C:\ProgramData\rattail\rattail.conf
+
+   [rattail.filemon]
+   monitor = incoming
+
+   incoming.dirs = C:\rattail-test\incoming
+   incoming.actions = copy, delete
+   incoming.action.copy.func = rattail.files:locking_copy
+   incoming.action.copy.args = C:\rattail-test\incoming\processed
+   incoming.action.delete.func = os:remove
+
+
+   ##############################
+   # logging
+   ##############################
+
+   [handler_file]
+   args = (r'C:\ProgramData\rattail\log\filemon.log', 'a', 1000000, 20, 'utf_8')
+
+Again you might make sure the ``rattail`` user has read access to the
+file.
+
+
+Testing the Setup
+-----------------
+
+Once all the above is in place, your basic configuration is complete,
+and you can move on to registering and starting the service; see
+:doc:`/base/install/windows/filemon/register` and
+:doc:`/base/install/windows/filemon/start`.
+
+If the service is working properly then you should be able to put a
+file in the ``C:\rattail-test\incoming`` folder, and filemon should
+immediately "move" it to ``C:\rattail-test\incoming\processed``
+(actually it copies the file, then deletes original, though it could
+be configured to truly move instead).
+
+The service should log its operations to file, at
+``C:\ProgramData\rattail\log\filemon.log``

docs/base/install/windows/filemon/config/index.rst

@@ -0,0 +1,20 @@
+
+===============
+ Configuration
+===============
+
+As usual "the devil is in the details" when it comes to configuration.
+
+The first point we should make is that there are many ways to go about
+this.  Some different approaches are listed a bit later on.
+
+But for starters we want to use a "safe" approach which is more likely
+to work out of the box.  So that will be described first.
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents:
+
+   overview
+   basic
+   variations

docs/base/install/windows/filemon/config/overview.rst

@@ -0,0 +1,33 @@
+
+.. highlight:: ini
+
+==========
+ Overview
+==========
+
+For more general background on Rattail config, see
+:doc:`/base/config/index`.
+
+While it is possible to store config in a DB (see
+:doc:`/base/config/db`), we will not address that here.  All config is
+presumed to exist in files, at least from the perspective of the
+Rattail File Monitor service.  As a rule we avoid DB interactions in
+the filemon to keep its operation as simple as possible.  (Everything
+"interesting" happens on the Linux server.)
+
+The filemon service uses the Windows API to obtain the "default"
+location of the config file.  It is not possible to directly tell the
+service which config file to use, it always will read the default
+path, which is: ``C:\ProgramData\rattail\rattail.conf``
+
+However we still want it to read ``filemon.conf`` instead of
+``rattail.conf`` - and that is possible by way of a special config
+entry within ``rattail.conf``::
+
+   [rattail.config]
+   winsvc.RattailFileMonitor = C:\ProgramData\rattail\filemon.conf
+
+So really when the service starts it first reads ``rattail.conf``, but
+sees that special entry and then reads ``filemon.conf`` *instead*.
+End result is as if it just read ``filemon.conf`` to begin with.  (See
+:doc:`/base/config/inheritance` for more on how some of that works.)

docs/base/install/windows/filemon/config/variations.rst

@@ -0,0 +1,35 @@
+
+.. highlight:: ini
+
+==================
+ Other Approaches
+==================
+
+Here are some variations on the config theme which you may find
+useful.
+
+
+Leveraging Site-Wide Config
+===========================
+
+It is possible to maintain a single "site-wide" config file, which
+your "machine-wide" config inherits from (see :ref:`site-wide-config`
+and :ref:`config-inheritance`).
+
+If you do this, it usually means that your Linux server is running
+Samba and exposing a share which includes the site-wide config
+file(s).  We will assume that scenario here, but we assume that part
+is already setup - it will not be described.
+
+So let's assume then that you have a Linux server named
+``poser-server`` and it exposes a ``rattail`` share, with a ``config``
+folder and ``site.conf`` within that.  So then in your machine-wide
+config on the Windows side, you include it by adding this to
+``C:\ProgramData\rattail\rattail.conf``::
+
+   [rattail.config]
+   include = \\poser-server\rattail\config\site.conf
+
+If you do this then you can also *remove* (most) anything from your
+machine-wide config file, which is also defined in the site-wide
+config file.

docs/base/install/windows/filemon/index.rst

@@ -0,0 +1,19 @@
+
+==============
+ File Monitor
+==============
+
+Rattail File Monitor is a Windows service which can watch some
+folder(s) and when new files appear, take action(s) on them.
+
+It is the only "officially" supported Rattail software to run on the
+Windows platform.
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents:
+
+   overview
+   config/index
+   register
+   start

docs/base/install/windows/filemon/overview.rst

@@ -0,0 +1,19 @@
+
+==========
+ Overview
+==========
+
+For general background on the Rattail File Monitor see
+:doc:`/base/filemon/index`.
+
+In the context of Windows, we should point out that the Rattail File
+Monitor runs as a proper Windows service, which can be started,
+stopped, and otherwise interacted with, the same as for any Windows
+service.
+
+It uses the Windows API to monitor, which means that it does not
+"poll" the folders directly but rather the Windows API will notify the
+filemon when new files appear etc.
+
+Under normal circumstances it should run "forever" regardless of
+whether anyone is currently logged into the Windows machine.

docs/base/install/windows/filemon/register.rst

@@ -0,0 +1,55 @@
+
+.. highlight:: sh
+
+=========================
+ Registering the Service
+=========================
+
+Note that all commands on this page must be ran in an *admin console*
+(right-click on ``cmd.exe``, run as administrator).
+
+At minimum you must register the service in order to use it.  Here is
+the most basic command you can use for that::
+
+   rattail filemon install
+
+However you will most likely want the service startup set to
+"automatic" - and you may also need to set it to run as a particular
+user account (see :doc:`/base/install/windows/user`).
+
+You can take care of all that at once with the command::
+
+   rattail filemon install --auto-start --username rattail
+
+This will register the service (so it's visible in Windows Services)
+and set it to automatic startup and to run as ``rattail`` user.
+
+(If the command fails then please be sure you are running an *admin
+console*.)
+
+Note that the service will *not* have been started yet.  Before you
+can do that though you will need to configure it; see
+:doc:`config/index` if you've not already done that.
+
+
+.. _unregister-windows-filemon:
+
+Unregistering the Service
+=========================
+
+To *unregister* the filemon service, you can do (again, in an *admin
+console*):
+
+.. code-block:: sh
+
+   rattail filemon remove
+
+Note that if you have the Windows Services snap-in open, or possibly
+one of a few other things, the service may not truly be removed until
+you close those things.  For more info see this `Stack Overflow
+post`_.
+
+.. _Stack Overflow post: https://stackoverflow.com/questions/20561990/how-to-solve-the-specified-service-has-been-marked-for-deletion-error
+
+You can close, then re-open Windows Servies snap-in to see if it has
+been truly removed from that list.

docs/base/install/windows/filemon/start.rst

@@ -0,0 +1,59 @@
+
+======================
+ Starting the Service
+======================
+
+If you have already registered and configured the service, then you
+can start it.  See also :doc:`register` and :doc:`config/index`.
+
+Most typically you would probably just open the Windows Services
+snap-in (``services.msc``), locate the Rattail File Monitor service in
+the list, right-click that and choose Start.
+
+You may encounter problems when first starting the service; if so see
+the Troubleshooting section below.
+
+If things are working "normally" then the filemon service should be
+writing a log file (e.g. ``C:\ProgramData\rattail\log\filemon.log``),
+so check that to be sure it's doing what you expect.
+
+
+Stopping the Service
+--------------------
+
+As with starting, you probably just want to use the Windows Services
+snap-in to stop the service.  Locate it in the list, right-click and
+choose Stop.
+
+
+Troubleshooting
+---------------
+
+Note that starting the service may fail, for any of a number of
+reasons.  Here we list some we've encountered, with tips for fixing
+each.
+
+You may encounter other issues not addressed here; if so please file a
+bug report at `<https://redmine.rattailproject.org>`_.
+
+
+Error 5: Access is denied
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It's possible this may occur due to multiple underlying issues, but at
+least one of them has a straightforward fix.
+
+If you did not install Python "for all users" but rather just clicked
+through with the "default" install (see
+:doc:`/base/install/windows/python`), then odds are the ``rattail``
+user (or whoever the service runs as; see
+:doc:`/base/install/windows/user`) does not have permission to invoke
+the Python executable.
+
+The fix in this case is to uninstall "everything" (i.e. "unwind"
+everything you installed per this manual; see
+:doc:`/base/install/windows/index`) and then re-install, this time
+making sure to install Python "for all users".
+
+Note that before uninstalling any software you should maybe unregister
+the filemon service first; see :ref:`unregister-windows-filemon`.