From 47fb1e451a9db6f68369e121d5e69c0ab3c2ea56 Mon Sep 17 00:00:00 2001 From: Lance Edgar Date: Sat, 30 Oct 2021 15:09:09 -0500 Subject: [PATCH] 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 | 2 + docs/base/config/paths.rst | 4 + docs/base/filemon.rst | 5 - docs/base/filemon/index.rst | 11 + docs/base/filemon/overview.rst | 22 ++ docs/base/index.rst | 2 +- docs/base/install/common.rst | 2 + docs/base/install/index.rst | 4 +- docs/base/install/windows.rst | 243 ------------------ .../install/windows/filemon/config/basic.rst | 198 ++++++++++++++ .../install/windows/filemon/config/index.rst | 20 ++ .../windows/filemon/config/overview.rst | 33 +++ .../windows/filemon/config/variations.rst | 35 +++ docs/base/install/windows/filemon/index.rst | 19 ++ .../base/install/windows/filemon/overview.rst | 19 ++ .../base/install/windows/filemon/register.rst | 55 ++++ docs/base/install/windows/filemon/start.rst | 59 +++++ docs/base/install/windows/index.rst | 23 ++ docs/base/install/windows/pip.rst | 36 +++ docs/base/install/windows/python.rst | 117 +++++++++ docs/base/install/windows/pywin32.rst | 43 ++++ docs/base/install/windows/rattail.rst | 20 ++ docs/base/install/windows/user.rst | 77 ++++++ docs/conf.py | 2 +- 24 files changed, 799 insertions(+), 252 deletions(-) delete mode 100644 docs/base/filemon.rst create mode 100644 docs/base/filemon/index.rst create mode 100644 docs/base/filemon/overview.rst delete mode 100644 docs/base/install/windows.rst create mode 100644 docs/base/install/windows/filemon/config/basic.rst create mode 100644 docs/base/install/windows/filemon/config/index.rst create mode 100644 docs/base/install/windows/filemon/config/overview.rst create mode 100644 docs/base/install/windows/filemon/config/variations.rst create mode 100644 docs/base/install/windows/filemon/index.rst create mode 100644 docs/base/install/windows/filemon/overview.rst create mode 100644 docs/base/install/windows/filemon/register.rst create mode 100644 docs/base/install/windows/filemon/start.rst create mode 100644 docs/base/install/windows/index.rst create mode 100644 docs/base/install/windows/pip.rst create mode 100644 docs/base/install/windows/python.rst create mode 100644 docs/base/install/windows/pywin32.rst create mode 100644 docs/base/install/windows/rattail.rst create mode 100644 docs/base/install/windows/user.rst diff --git a/docs/base/config/inheritance.rst b/docs/base/config/inheritance.rst index 2edbc28..f941bd8 100644 --- a/docs/base/config/inheritance.rst +++ b/docs/base/config/inheritance.rst @@ -1,6 +1,8 @@ .. highlight:: ini +.. _config-inheritance: + Config File Inheritance ======================= diff --git a/docs/base/config/paths.rst b/docs/base/config/paths.rst index 0b2c43f..67bf4aa 100644 --- a/docs/base/config/paths.rst +++ b/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 --------- diff --git a/docs/base/filemon.rst b/docs/base/filemon.rst deleted file mode 100644 index 8c88f81..0000000 --- a/docs/base/filemon.rst +++ /dev/null @@ -1,5 +0,0 @@ - -File Monitoring -=============== - -TODO diff --git a/docs/base/filemon/index.rst b/docs/base/filemon/index.rst new file mode 100644 index 0000000..df10612 --- /dev/null +++ b/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 diff --git a/docs/base/filemon/overview.rst b/docs/base/filemon/overview.rst new file mode 100644 index 0000000..b0dcd90 --- /dev/null +++ b/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. diff --git a/docs/base/index.rst b/docs/base/index.rst index 7219124..2323063 100644 --- a/docs/base/index.rst +++ b/docs/base/index.rst @@ -16,7 +16,7 @@ Base Layer email/index cron supervisor - filemon + filemon/index mailmon upgrades handlers/index diff --git a/docs/base/install/common.rst b/docs/base/install/common.rst index 5b78399..f5003eb 100644 --- a/docs/base/install/common.rst +++ b/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 ------------ diff --git a/docs/base/install/index.rst b/docs/base/install/index.rst index 02ba7d3..d655956 100644 --- a/docs/base/install/index.rst +++ b/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 diff --git a/docs/base/install/windows.rst b/docs/base/install/windows.rst deleted file mode 100644 index 3e9df55..0000000 --- a/docs/base/install/windows.rst +++ /dev/null @@ -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 -``_. - -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 -``_. - -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 diff --git a/docs/base/install/windows/filemon/config/basic.rst b/docs/base/install/windows/filemon/config/basic.rst new file mode 100644 index 0000000..c12def7 --- /dev/null +++ b/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`` diff --git a/docs/base/install/windows/filemon/config/index.rst b/docs/base/install/windows/filemon/config/index.rst new file mode 100644 index 0000000..4048714 --- /dev/null +++ b/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 diff --git a/docs/base/install/windows/filemon/config/overview.rst b/docs/base/install/windows/filemon/config/overview.rst new file mode 100644 index 0000000..ade080b --- /dev/null +++ b/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.) diff --git a/docs/base/install/windows/filemon/config/variations.rst b/docs/base/install/windows/filemon/config/variations.rst new file mode 100644 index 0000000..303202b --- /dev/null +++ b/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. diff --git a/docs/base/install/windows/filemon/index.rst b/docs/base/install/windows/filemon/index.rst new file mode 100644 index 0000000..a057b82 --- /dev/null +++ b/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 diff --git a/docs/base/install/windows/filemon/overview.rst b/docs/base/install/windows/filemon/overview.rst new file mode 100644 index 0000000..83ce689 --- /dev/null +++ b/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. diff --git a/docs/base/install/windows/filemon/register.rst b/docs/base/install/windows/filemon/register.rst new file mode 100644 index 0000000..7ca2489 --- /dev/null +++ b/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. diff --git a/docs/base/install/windows/filemon/start.rst b/docs/base/install/windows/filemon/start.rst new file mode 100644 index 0000000..00fb0fd --- /dev/null +++ b/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 ``_. + + +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`. diff --git a/docs/base/install/windows/index.rst b/docs/base/install/windows/index.rst new file mode 100644 index 0000000..0e8e707 --- /dev/null +++ b/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 diff --git a/docs/base/install/windows/pip.rst b/docs/base/install/windows/pip.rst new file mode 100644 index 0000000..165fa83 --- /dev/null +++ b/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/ diff --git a/docs/base/install/windows/python.rst b/docs/base/install/windows/python.rst new file mode 100644 index 0000000..f7f8244 --- /dev/null +++ b/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: ``_ + +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 +``_ + +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/ diff --git a/docs/base/install/windows/pywin32.rst b/docs/base/install/windows/pywin32.rst new file mode 100644 index 0000000..943ea26 --- /dev/null +++ b/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 +``_. + +Right-click the installer file and choose "Run as administrator" to +launch it. + +All defaults should be fine; click through to complete the +installation. diff --git a/docs/base/install/windows/rattail.rst b/docs/base/install/windows/rattail.rst new file mode 100644 index 0000000..86e258b --- /dev/null +++ b/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. diff --git a/docs/base/install/windows/user.rst b/docs/base/install/windows/user.rst new file mode 100644 index 0000000..9d6472d --- /dev/null +++ b/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. diff --git a/docs/conf.py b/docs/conf.py index ce60e26..934956e 100644 --- a/docs/conf.py +++ b/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'