rattail-manual/docs/base/install/windows.rst

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