rattail-manual/docs/base/install/windows/filemon/config/basic.rst

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