docs: add "intro" doc to better describe integration modes
This commit is contained in:
parent
066fcb857f
commit
0ab511d841
2 changed files with 124 additions and 0 deletions
|
|
@ -24,6 +24,7 @@ include:
|
|||
:maxdepth: 2
|
||||
:caption: Documentation:
|
||||
|
||||
narr/intro
|
||||
narr/install
|
||||
narr/auth
|
||||
narr/features
|
||||
|
|
|
|||
123
docs/narr/intro.rst
Normal file
123
docs/narr/intro.rst
Normal file
|
|
@ -0,0 +1,123 @@
|
|||
|
||||
==============
|
||||
Introduction
|
||||
==============
|
||||
|
||||
This page hopefully conveys the what and why of WuttaFarm as a project.
|
||||
|
||||
WuttaFarm can serve as a "supplement" or "alternative" to `farmOS
|
||||
<https://farmos.org>`_, depending on your needs. It has 3 distinct
|
||||
"modes" of operation:
|
||||
|
||||
* :ref:`wrapper (API only) <wrapper-mode>`
|
||||
* :ref:`mirror (2-way sync) <mirror-mode>`
|
||||
* :ref:`standalone <standalone-mode>`
|
||||
|
||||
|
||||
Rationale
|
||||
---------
|
||||
|
||||
This project exists primarily to scratch a personal itch, but the hope
|
||||
of course is that others will find it useful also. This is partly why
|
||||
the app has different integration modes.
|
||||
|
||||
Realistically this is not (yet?) meant to be a "finished" app per se.
|
||||
In that sense it is akin to farmOS itself, i.e. "part app, part
|
||||
framework" which can be extended where needed.
|
||||
|
||||
It purposefully does not try to re-invent every wheel provided by
|
||||
farmOS. But it does re-invent "certain types" of wheels, to some
|
||||
degree, depending on which mode is used.
|
||||
|
||||
It should also be mentioned, the 3 "modes" are essentially just
|
||||
abstractions for sake of convenience. The framework allows one to
|
||||
customize however you want regardless of the "mode" in effect.
|
||||
|
||||
The target audience I suppose, is folks like me who prefer Python over
|
||||
PHP, and can customize away without having to touch Drupal.
|
||||
|
||||
|
||||
.. _wrapper-mode:
|
||||
|
||||
Wrapper Mode (API only)
|
||||
-----------------------
|
||||
|
||||
This is the default integration mode for the app. In wrapper mode,
|
||||
WuttaFarm UI will only expose views which display/modify farmOS data
|
||||
*directly* via its JSONAPI. The app will not expose any views which
|
||||
operate on its "native" tables (for assets, logs etc.).
|
||||
|
||||
Any data model extensions needed must of course be managed on the
|
||||
farmOS side, since the native tables are not used for this mode.
|
||||
|
||||
This mode is simplest (for farmOS integration) since every user action
|
||||
goes immeditely through the API. There is no "sync" or caching
|
||||
involved.
|
||||
|
||||
There is one known issue with this mode, and it's kind of a bummer:
|
||||
|
||||
When viewing the "list" page for any record type (e.g. Animal Assets),
|
||||
due to a quirk with the JSONAPI, you can only see the "first 50"
|
||||
results in the listing. However you can still filter/sort the
|
||||
records, to hopefully find what you need. And you can still view
|
||||
*any* record if you have its URL (which you can normally figure out
|
||||
from the farmOS UUID value).
|
||||
|
||||
|
||||
.. _mirror-mode:
|
||||
|
||||
Mirror Mode (2-way sync)
|
||||
------------------------
|
||||
|
||||
This mode exposes the native table views in addition to direct API
|
||||
views. It's sort of a combination of the wrapper and standalone
|
||||
modes, with an extra daemon process to handle some of the sync tasks.
|
||||
|
||||
(It's also the most complex mode to setup; more "moving parts" which
|
||||
means potentially more to go wrong and require troubleshooting.)
|
||||
|
||||
Again this depends on your actual use case, but a "complete" setup for
|
||||
this mode would mean:
|
||||
|
||||
* changes made in WuttaFarm are synced to farmOS via JSONAPI
|
||||
* changes made in farmOS are synced to WuttaFarm via webhook+daemon
|
||||
|
||||
The latter includes changes made via the farmOS proper web app, and/or
|
||||
changes made via the "direct API" views within WuttaFarm (or anything
|
||||
else that invokes the farmOS API). This requires the extra daemon
|
||||
process (running alongside the WuttaFarm web app process), as well as
|
||||
the `webhooks module
|
||||
<https://farmos.discourse.group/t/using-the-webhooks-module/2490>`_ on
|
||||
the farmOS side.
|
||||
|
||||
It's possible to extend the data model on the WuttaFarm side with or
|
||||
without doing so on the farmOS side, and vice versa. Although
|
||||
regardless you may have to take both into consideration for your
|
||||
overall sync needs.
|
||||
|
||||
There is support for "full" data import/export between systems in both
|
||||
directions, WuttaFarm <=> farmOS. Limited of course by the common
|
||||
schema they share etc. This can be leveraged easily to include
|
||||
nightly "data diff" checks, ensuring all stays in sync.
|
||||
|
||||
|
||||
|
||||
.. _standalone-mode:
|
||||
|
||||
Standalone Mode
|
||||
---------------
|
||||
|
||||
This mode exposes *only* the native table views, and none of the
|
||||
"direct API" views. This requires no farmOS at all.
|
||||
|
||||
This lets you customize the data model as needed, using SQLAlchemy and
|
||||
Alembic, as does the mirror mode. However no "sync" is required so
|
||||
you don't have to consider the farmOS data model.
|
||||
|
||||
While the wrapper mode is simplest for farmOS integration, this
|
||||
standalone mode is even simpler, technically speaking. It should work
|
||||
well if you just need the basic record-keeping aspects.
|
||||
|
||||
The main downside with this mode is there is not (yet?) any
|
||||
mapping/geometry support, nor is there support for image/file
|
||||
attachments.
|
||||
Loading…
Add table
Add a link
Reference in a new issue