Overhaul docs for Windows filemon install

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

docs/base/config/inheritance.rst

@@ -1,6 +1,8 @@
 
 .. highlight:: ini
 
+.. _config-inheritance:
+
 Config File Inheritance
 =======================
 

docs/base/config/paths.rst

@@ -46,6 +46,8 @@ defines the config needed to run bouncer and uses a custom logging file.
 defines the config needed to run mailmon and uses a custom logging file.
 
 
+.. _machine-wide-config:
+
 Machine-Wide
 ------------
 
@@ -57,6 +59,8 @@ The convention here is to place the file at ``/etc/rattail/rattail.conf``
 although you could do whatever you like.
 
 
+.. _site-wide-config:
+
 Site-Wide
 ---------
 

docs/base/filemon.rst

@@ -1,5 +0,0 @@
-
-File Monitoring
-===============
-
-TODO

docs/base/filemon/index.rst

@@ -0,0 +1,11 @@
+
+File Monitoring
+===============
+
+This section of the manual describes the Rattail File Monitor
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents:
+
+   overview

docs/base/filemon/overview.rst

@@ -0,0 +1,22 @@
+
+==========
+ Overview
+==========
+
+Rattail File Monitor is a "service" (or "daemon") which does "one
+thing" - it watches some folder(s) and when new files appear it takes
+action(s) on them.  It runs "forever" unless stopped, regardless of
+whether anyone is currently logged onto the machine.
+
+In many cases the "action" is just to copy (or move) the file
+elsewhere, for further processing.  In some cases it may be to "copy"
+the file directly to a printer port, e.g. LPT1.
+
+Sometimes the action will be to "import" and/or "process" data from
+the file, updating the Rattail DB or other systems.
+
+However the action may be anything at all.  Most common actions, e.g.
+copying a file to another location, are provided by way of Python
+functions or classes, in other words Python code.  But you can also
+invoke an arbitrary command line for the action, which needn't involve
+Python at all.

docs/base/index.rst

@@ -16,7 +16,7 @@ Base Layer
    email/index
    cron
    supervisor
-   filemon
+   filemon/index
    mailmon
    upgrades
    handlers/index

docs/base/install/common.rst

@@ -37,6 +37,8 @@ Then you would install that to your virtual environment like so::
    pip install -e ./theo
 
 
+.. _rattail-sanity-check:
+
 Sanity Check
 ------------
 

docs/base/install/index.rst

@@ -11,8 +11,8 @@ software suite.  Things *should* work on Windows but the only thing
 
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
    :caption: Contents:
 
    common
-   windows
+   windows/index

docs/base/install/windows.rst

@@ -1,243 +0,0 @@
-
-Installing on Windows
-=====================
-
-Here we describe the prerequisites etc. for a Rattail install on Windows.
-
-
-Installing Python
------------------
-
-There are surely lots of ways to install Python on Windows, and these
-steps are not necessarily "superior" to other methods, if you know
-what you're doing.  But they do have the benefit of being relatively
-well-tested in production environments.
-
-
-32 bit vs. 64 bit
-~~~~~~~~~~~~~~~~~
-
-In some cases, your Rattail app(s) may need to load and invoke code
-from various compiled libraries.  The most common scenario is that the
-app needs to read data from an ODBC connection which uses a binary
-driver.
-
-Sometimes these libraries are only available in a 32 bit version.  If
-this is the case for you then you must install 32 bit Python, even on
-a 64 bit machine.
-
-.. note::
-   The above statements "used to be true" but it's been a while since
-   I had my head in that game, and much may have changed.
-
-
-Python
-~~~~~~
-
-First of course you'll need Python itself, available at
-`<https://www.python.org/downloads/windows/>`_.
-
-You are encouraged to download the latest version available, although
-in practice older versions will have received more production testing
-in the wild.  At least, it probably should be 3.6 or later.
-
-Remember to watch for the distinction between 32 bit and 64 bit, if
-applicable (see above).
-
-Download the appropriate installer and run it.  If there is an option
-to add Python to your ``PATH`` variable, it's recommended that you do
-so.
-
-At this point you should be able to open a (new!) command line and
-confirm ``python.exe`` is usable:
-
-.. code-block:: none
-
-   C:\>python --version
-   Python 3.7.3
-
-
-If that doesn't work, you may need to manually add e.g.
-``C:\Python37;C:\Python37\Scripts`` to your `PATH environment
-variable`_.
-
-.. _PATH environment variable: http://www.computerhope.com/issues/ch000549.htm
-
-
-Python for Windows Extensions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The situation on Windows is a little more complicated, and the short
-version is that you must also install Mark Hammond's "Python for
-Windows Extensions" package, available at
-`<https://github.com/mhammond/pywin32/releases>`_.
-
-The specific version you download should match the version of Python
-you installed, above.  Again pay attention to 32 bit vs. 64 bit if
-applicable.
-
-Run the installer; all defaults are fine.
-
-
-Pip
-~~~
-
-If you just downloaded a fresh copy of Python (above), then you should
-already have a copy of pip.  If you are working with an older install
-of Python etc. it is possible that you may not yet have pip.  Open a
-command line to find out:
-
-.. code-block:: none
-
-   C:\>pip --version
-   pip 21.1.3 from C:\Python37\lib\site-packages (python 3.7)
-
-If that doesn't work (but ``python --version`` does) then you probably
-need to install pip.  The recommended method is via the ``get-pip.py``
-script according to `these instructions`_.
-
-.. _these instructions: https://pip.pypa.io/en/latest/installing.html#install-pip
-
-
-Installing Rattail
-------------------
-
-See :doc:`common` for more background but if you're just after the
-filemon service then you probably only need to do this:
-
-.. code-block:: sh
-
-   pip install rattail
-
-
-File Monitor Setup
-------------------
-
-With the above in place we now can register the filemon as a proper
-Windows service.
-
-But before we do so we should add some basic config files for it.
-This is because the Windows service has a hard-coded place to look for
-config, so the service will fail to start if the config is not there.
-
-
-File Monitor Config
-~~~~~~~~~~~~~~~~~~~
-
-First create a folder at ``C:\ProgramData\rattail``.
-
-Then create a file at ``C:\ProgramData\rattail\rattail.conf`` with
-contents like:
-
-.. code-block:: ini
-
-   ############################################################
-   #
-   # rattail config
-   #
-   ############################################################
-
-
-   ##############################
-   # rattail
-   ##############################
-
-   [rattail]
-   production = true
-
-   [rattail.config]
-   include = \\my-rattail-server\rattail\config\site.conf
-   winsvc.RattailFileMonitor = C:\ProgramData\rattail\filemon.conf
-
-
-   ##############################
-   # logging
-   ##############################
-
-   [handler_file]
-   args = (r'C:\ProgramData\rattail\log\rattail.log', 'a', 1000000, 20, 'utf_8')
-
-
-Then create a file at ``C:\ProgramData\rattail\filemon.conf`` with
-contents like:
-
-.. code-block:: ini
-
-   ############################################################
-   #
-   # filemon config
-   #
-   ############################################################
-
-
-   ##############################
-   # rattail
-   ##############################
-
-   [rattail.config]
-   include = C:\ProgramData\rattail\rattail.conf
-
-   [rattail.filemon]
-   monitor = 
-           first
-           second
-           third
-
-   first.dirs = C:\folders\first
-   first.actions = copy, delete
-   first.action.copy.func = rattail.files:locking_copy
-   first.action.copy.args = \\my-rattail-server\rattail\files\incoming\first
-   first.action.delete.func = os:remove
-
-   second.dirs = C:\folders\second
-   second.actions = copy, delete
-   second.action.copy.func = rattail.files:locking_copy
-   second.action.copy.args = \\my-rattail-server\rattail\files\incoming\second
-   second.action.copy.retry_attempts = 6
-   second.action.copy.retry_delay = 10
-   second.action.delete.func = os:remove
-   second.stop_on_error = true
-
-   third.dirs = C:\folders\third
-   third.watch_locks = true
-   third.actions = custom, backup
-   third.action.custom.func = poser.filemon_actions:my_custom_func
-   third.action.custom.args = foo
-   third.action.backup.func = rattail.files:overwriting_move
-   third.action.backup.args = C:\folders\third\backup
-
-
-   ##############################
-   # logging
-   ##############################
-
-   [handler_file]
-   args = (r'C:\ProgramData\rattail\log\filemon.log', 'a', 1000000, 20, 'utf_8')
-
-
-Registering the Service
-~~~~~~~~~~~~~~~~~~~~~~~
-
-Note that this must be done in an Administrator console!
-
-.. code-block:: sh
-
-   rattail filemon install --auto-start --username rattail
-
-You are encouraged to use ``rattail`` for the username, but any will
-do if you have another preference.
-
-One common pattern is to have a shared site-wide config provided by
-the "real" Rattail server (presumed to be Linux), which is "included"
-by this machine's config.  An example of this is shown above within
-the ``rattail.conf`` file.
-
-The user which the filemon service runs as, must have access to any
-shares provided by other machines, where it needs to read/write files
-etc.
-
-Note that to *unregister* the filemon service, you can do:
-
-.. code-block:: sh
-
-   rattail filemon remove

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`.

docs/base/install/windows/index.rst

@@ -0,0 +1,23 @@
+
+Installing on Windows
+=====================
+
+The only thing "officially" supported on Windows is the Rattail File
+Monitor service.  As such that is the main focus for this section of
+the manual.
+
+Other things are likely possible and some may even be straightforward,
+so if you want to experiment then hopefully some of this is still
+useful.
+
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents:
+
+   python
+   pip
+   pywin32
+   rattail
+   user
+   filemon/index

docs/base/install/windows/pip.rst

@@ -0,0 +1,36 @@
+
+=====
+ Pip
+=====
+
+If you have a "recent" version of Python installed then you should
+already have Pip installed as well.
+
+
+Sanity Check
+============
+
+Just to be sure you have it, open a new console (``cmd.exe``) and run
+a version check:
+
+.. code-block:: none
+
+   C:\>pip --version
+   pip 21.2.3 from C:\Program Files\Python39\lib\site-packages\pip (python 3.9)
+
+If that doesn't work then maybe try to close and re-open your console
+first.
+
+Note that the Pip version check is only expected to work if the Python
+version check *also* worked.  So maybe see also docs for that, in
+:ref:`python-sanity-check`.
+
+If the Python version check works but Pip still does not then maybe
+your Python version is too old?  In that case you probably need to
+install Pip.  The recommended method is via the ``get-pip.py`` script
+according to `these instructions`_.
+
+.. _these instructions: https://pip.pypa.io/en/latest/installing.html#install-pip
+
+If you're sure Pip is installed and yet the version check still fails,
+please file a bug report at https://redmine.rattailproject.org/

docs/base/install/windows/python.rst

@@ -0,0 +1,117 @@
+
+========
+ Python
+========
+
+You will need Python in order to use any Rattail software on Windows.
+
+You can get it from: `<https://www.python.org/downloads/windows/>`_
+
+The notes below should help you decide which version to install etc.
+
+
+Which Version?
+--------------
+
+In general you are encouraged to use the "latest stable" version of
+Python unless you have a reason to be more conservative.
+
+As of this writing Python 3.10 is the "latest" but has not yet been
+tested in production, so it is suggested to use 3.9 instead, since
+that has been tested.  That is the situation "today" (Oct 2021) and
+eventually should change.
+
+Any other Python-based packages you may need to install, must of
+course be compatible with the version of Python you have.  This
+includes Rattail itself (see :doc:`rattail`) but also e.g. the pywin32
+library (see :doc:`pywin32`) and perhaps wxPython.  You may want to
+gather your download links ahead of time to be sure they all are for
+the same Python version.
+
+Note that in general, e.g. if you only need the Rattail File Monitor,
+then you will not likely need to "upgrade" Python anytime soon.  If
+you install 3.9 for instance then it should continue to work fine for
+the forseeable future.
+
+
+32 bit vs. 64 bit
+-----------------
+
+In some cases, your Rattail app(s) may need to load and invoke code
+from various compiled libraries.  The most common scenario is that the
+app needs to read data from an ODBC connection which uses a binary
+driver.
+
+Sometimes these libraries are only available in a 32 bit version.  If
+this is the case for you then you must install 32 bit Python, even on
+a 64 bit machine.
+
+Again you may want to gather all download links ahead of time to be
+sure everything matches, for both Python version and "bitness".
+
+.. note::
+   The above statements "used to be true" but it's been a while since
+   I had my head in that game, and much may have changed.
+
+   In particular if you only need the Rattail File Monitor, and only
+   need it to do standard tasks like moving files to a Linux server,
+   then there should be no binary libraries involved and you will be
+   fine to use 64bit Python.
+
+
+Installation
+------------
+
+Download the appropriate installer from
+`<https://www.python.org/downloads/windows/>`_
+
+Right-click the installer file and choose "Run as administrator" to
+launch it.
+
+If you are wanting to use the Rattail File Monitor then you should
+install Python "for all users" - this requires that you "customize"
+the installation.  In other words don't just click "Install Now" but
+instead click "Customize" and then select the option to install for
+all users.
+
+You should also see an option to "Add Python to your PATH variable" -
+it is recommended that you choose this unless you have a reason not
+to.
+
+
+.. _python-sanity-check:
+
+Sanity Check
+------------
+
+Once the installation completes, you should open a *new* console
+(``cmd.exe``) and confirm that ``python.exe`` is usable:
+
+.. code-block:: none
+
+   C:\>python --version
+   Python 3.9.7
+
+If that doesn't work then it is probably due to one of 2 things:
+
+If your console window was already open during the install, please close
+it and re-open, then it should work.
+
+Or, if still no good, then you probably did not add Python to your
+PATH variable during the install.  You can of course re-install, but
+you can also manually add it to PATH if you prefer.  
+
+If you want to manually add Python to PATH then see e.g. `this
+article`_ for instructions.  You will need to add 2 folders to the
+variable, paths of which may vary per your install.  If you installed
+"for all users" as described above then the folders are probably
+something like:
+
+* ``C:\Program Files\Python39``
+* ``C:\Program Files\Python39\Scripts``
+
+.. _this article: http://www.computerhope.com/issues/ch000549.htm
+
+If PATH looks good and you re-opened your console, and things still do
+not work, then please file a bug report at
+https://redmine.rattailproject.org/

docs/base/install/windows/pywin32.rst

@@ -0,0 +1,43 @@
+
+===============================
+ Python for Windows Extensions
+===============================
+
+Python for Windows Extensions (aka. "pywin32") is a set of libraries
+which allows access to the Win32 API etc.
+
+If you want the Rattail File Monitor then you *will* need to install
+pywin32.  It may be optional if you have other aims, but it is
+generally recommended for everyone on Windows.
+
+
+Which Version?
+--------------
+
+As with Python itself, you are encouraged to use the "latest stable"
+version of pywin32 unless you have a reason to be more conservative.
+
+Other than that you just need to make sure the Python version you
+have, matches that required by the pywin32 version you have.  And the
+"bitness" must match as well, i.e. 32bit vs. 64bit.
+
+As of this writing Python 3.9 with pywin32 302 is the "latest" combo
+tested in production.  That is the situation "today" (Oct 2021) and
+eventually should change.
+
+As with Python itself, you will not likely need to "upgrade" pywin32
+anytime soon.  If you install 302 for instance then it should continue
+to work fine for the forseeable future.
+
+
+Installation
+------------
+
+Download the appropriate installer from
+`<https://github.com/mhammond/pywin32/releases>`_.
+
+Right-click the installer file and choose "Run as administrator" to
+launch it.
+
+All defaults should be fine; click through to complete the
+installation.

docs/base/install/windows/rattail.rst

@@ -0,0 +1,20 @@
+
+=========
+ Rattail
+=========
+
+See :doc:`/base/install/common` for more background but if you're just after the
+filemon service then you probably only need to do this:
+
+.. code-block:: sh
+
+   pip install rattail
+
+See also :ref:`rattail-sanity-check`.
+
+Note that the above does not register the filemon service.  That comes
+later; see :doc:`filemon/index`.
+
+You may also need to install additional Rattail packages, e.g. to
+integrate with your POS system.  That is outside of our scope for now
+though.

docs/base/install/windows/user.rst

@@ -0,0 +1,77 @@
+
+============
+Windows User
+============
+
+In some cases, in particular if you want to use the Rattail File
+Monitor, then you may need to consider which Windows user account the
+service will run as.
+
+
+Why It Matters
+==============
+
+Rattail File Monitor does "one thing" - it watches some folder(s) and
+when new files appear it takes action(s) on them.
+
+Most often the "action" is just to copy (or move) the file elsewhere,
+for further processing.  In some cases it may be to "copy" the file
+directly to a printer port, e.g. LPT1.
+
+Most often the "destination" for files being copied, is actually a
+Linux server, which runs the "real" Rattail-based app(s).  This server
+exposes a CIFS share via Samba, and the filemon on Windows is able to
+copy files to the CIFS share easily enough.
+
+But usually the CIFS share will have some sort of user security in
+place, so not just anyone on the network can access it.  So we must
+run the filemon service as a particular user, which *does* have access
+to the share(s), and/or any other pertinent resources.
+
+
+Choosing a Username
+===================
+
+It is recommended to use the default username of ``rattail`` unless
+you have reasons to do otherwise.
+
+However there is no magic about that username, the main advantage to
+going with it is that all Rattail docs will use it, so you won't need
+to adjust any commands etc. when setting things up.
+
+Keep in mind that this user account will need to exist on the Windows
+machine (see below) but also may effectively need to exist within
+Samba on the Linux side.  Configuration of the latter is not our focus
+here, but just know that this may be more of a "network-wide" user
+account - depending on your use case.
+
+
+Active Directory
+================
+
+As of this writing no AD integration has been attempted.
+
+Only "local machine" user accounts are supported thus far.
+
+Note that CIFS behavior is such that if you create a "local" Windows
+user with the username of ``rattail`` and password ``rattailpass``,
+and then configure a Samba user account with the same credentials,
+then things should work.  (Please use a different password of course,
+that is just for example.)
+
+
+Creating the Account
+====================
+
+You probably already know how to create a user account, but if you
+prefer you can tell Rattail to do it for you.  In an admin console
+(right-click ``cmd.exe``, run as administrator) do:
+
+.. code-block:: sh
+
+   rattail make-user --system windows rattail
+
+This will create a "local machine" Windows account, with username
+``rattail`` and the password you specify (which you will be prompted
+for).  This account will be suitable for use with the Rattail File
+Monitor service.

docs/conf.py

@@ -22,7 +22,7 @@ master_doc = 'index'
 
 # -- Project information -----------------------------------------------------
 
-project = 'rattail-manual'
+project = 'Rattail Manual'
 copyright = '2021, Lance Edgar'
 author = 'Lance Edgar'