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.

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 Create the Database.

App Setup

The short version:

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 Wutta-Continuum. 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.

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

With that in place you should be able to login via OAuth2; see also Authentication.

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:

[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:

./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:

./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:

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