152 lines
4.4 KiB
ReStructuredText
152 lines
4.4 KiB
ReStructuredText
|
|
==============
|
|
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
|