wuttafarm/docs/narr/install.rst

==============
 Installation
==============

For now, these instructions mostly reflect my own dev workflow.  It
uses a Python virtual environment but no (Docker) containers.

Eventually it may make sense to add production deployment steps using
Docker etc. - but that will wait for now.


Requirements
------------

WuttaFarm is designed to run on a (Debian-based) Linux machine; YMMV
with others.


farmOS
~~~~~~

First you must have a *production* `farmOS`_ instance running
somewhere.  For more on that see `Hosting farmOS`_.

.. _farmOS: https://farmos.org
.. _Hosting farmOS: https://farmos.org/hosting/

This must use HTTPS for the OAuth2 workflows to work correctly.  (Not
sure but it may also need to be at the root of the domain, i.e.  no
subpath.)


Database
~~~~~~~~

You also must create a PostgreSQL (or MySQL) database for the
WuttaFarm app to use.  See also :ref:`wuttjamaican:create-appdb`.


App Setup
---------

The short version:

.. code-block:: sh

   python3 -m venv ./venv
   ./venv/bin/pip install WuttaFarm
   ./venv/bin/wuttafarm install

The app installer (last command above) will prompt you for DB
credentials, and the farmOS URL.

One of the questions is about data versioning with
:doc:`wutta-continuum:index`.  You should probaby enable that even
though as of writing the default is disabled.  It adds "revision
history" for most types of records in the WuttaFarm app DB.

When the installer completes it will output a command you can then use
to run the web app.  Do that and you can then view the app in a
browser at http://localhost:9080


OAuth2 Setup
------------

At this point the web app should be ready for OAuth2 login; however
the OAuth2 provider in farmOS needs some more config before it will
work.

WuttaFarm uses the default ``farm`` consumer, so the only thing you
should have to do here is edit that to add your redirect URL.  This
will vary based on your WuttaFarm site name, e.g.

.. code-block:: none

   https://wuttafarm.example.com/farmos/oauth/callback

With that in place you should be able to login via OAuth2; see also
:doc:`/narr/auth`.

However while you're there, you should also do some setup for the sake
of the farmOS → WuttaFarm data import.  This import will also use the
farmOS API and therefore also needs an oauth2 access token; however it
uses the Client Credentials workflow instead of the Authorization Code
workflow.  Therefore you must create a new *user* and a new OAuth2
*consumer* for it.

First add a new user in farmOS, named ``wuttafarm``.  It should
probably be given the Manager role, since WuttaFarm will eventually
also support "exporting" data back to farmOS.

Then add a new OAuth2 consumer (aka. client) with these attributes:

* **Label:** WuttaFarm
* **Client ID:** wuttafarm
* **New Secret:** (put something in here, to be used as client secret)
* **Grant Types:** Client Credentials, Refresh Token (maybe more?)
* **User:** wuttafarm
* **3rd Party?** yes
* **Confidential?** yes
* **Access Token Expiration Time:** maybe set to 3600? or maybe 300
  default is okay?
* **Allowed Origins:** put your oauth callback URL here (same as for
  default ``farm`` consumer)

WuttaFarm also needs to know the client secret for sake of running the
import; so add this to your ``app/wutta.conf`` file.  Of course
replace the value with whatever client secret you gave the new
consumer:

.. code-block:: ini

   [farmos.oauth2]
   importing.client_secret = you_cant_guess_me


Email Setup
-----------

WuttaFarm can send emails of various kinds; of note are:

* when user submits Feedback via button in top right of screen
* importer diff warning for farmOS → WuttaFarm

That last one is optional, triggered via the ``-W`` flag in the
importer command line.

Anyway the app basically assumes there is a Postfix or similar mail
server running on "localhost" which it can use as the SMTP server, and
which is in turn responsible for "really" sending the email out via
some configured relay.  This has always worked very well for me since
I tend to want to have email working for other reasons on each Linux
server I maintain.  (And since I have not traditionally used Docker
and/or containers.)

So if you need something else, touch base and we'll figure something
out.  But assuming localhost is okay to use:

In the web app menu, see Admin -> App Info and then click Configure.
Check the box to enable email and plug in the default sender and
recipient (which should be the admin responsible for the app).  I
often create an alias so I can use e.g. wuttafarm@edbob.org as
sender - aliased back to myself in case it generates bounces so I can
see them.

From there you can also see Admin -> Email Settings in the menu; this
lets you control and preview each type of email separately.


Import Data from farmOS
-----------------------

You must have done all the OAuth2 setup (previous section) before the
import will work.

But now that you did all that, importing should be quick and easy.

The very first import will be limited and "special" to account for any
users which were already created in WuttaFarm.  This command will
ensure WuttaFarm gets *all* user accounts and each is appropriately
mapped to the farmOS account:

.. code-block:: sh

   ./venv/bin/wuttafarm --runas farmos import-farmos User --key username

Note also the ``--runas farmos`` arg which helps the WuttaFarm data
versioning know "who" is responsible for the changes.  We use a
dedicated ``farmos`` user account in WuttaFarm, to represent the
farmOS system as a whole.

From now on you can run the "full" import normally:

.. code-block:: sh

   ./venv/bin/wuttafarm --runas farmos import-farmos

And it can sometimes be helpful to "double-check" in order to make
sure all data is fully synced:

.. code-block:: sh

   ./venv/bin/wuttafarm --runas farmos import-farmos --delete --dry-run -W