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`.  This feature will be leveraged more in
the future but for the moment doesn't do a whole lot in this app.  You
are encouraged to enable it anyway.

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


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