Work has begun on a simplified farmOS app that works offline in both browser and native app form. It is installable on Android and iOS devices. The goal is to create a fast and focused client app for day-to-day and in-the-field record keeping that stores data locally for offline use, and syncs back to a farmOS server when internet access is available.
The application consists of the main client, which provides the UI and core features, as well as native plugins, which provide specific support for native functionality, like the ability to persist data and access the camera.
The source code can be found here: https://github.com/farmOS/farmOS-client
This documentation is not complete. It is intended only for informational purposes at this time.
Please see the User's Guide for more information on how to install and use the client on your devices.
The client is built with Vue.js and Apache Cordova. Initially, the client and its native implementation were maintained as separate libraries. This was done with the aim of being able to isolate native functionality in Vue plugins that could be swapped out for browser-based plugins. This may not be strictly necessary in the future, but it does at least make for good separation of concerns.
The first thing of course is to clone the client repo from GitHub, and install the npm dependencies:
$ git clone https://github.com/farmOS/farmOS-client.git $ cd farmOS-client $ npm install
Note that the default branch for this repository is
develop should represent the most current set of complete features that
are only awaiting further testing before release. You should branch or fork
develop and submit pull requests to be merged back into it. The
deploy branch respresents the latest tagged release.
The browser-based development environment can be started by running the following command from the project root:
$ npm start
This will start the Webpack devServer, which will compile a development build and serve it from http://localhost:8080/. Changes saved to the files in your local repo will be hot reloaded automatically while the devServer is running.
Proxying a farmOS Docker container¶
By default, when the Webpack devServer starts, it will set up a proxy service,
which will route all AJAX requests and responses through
in order to prevent CORS errors. This is assumed to be the address of a local
farmOS development server running in a Docker container. This is probably the
easiest way to get a development backend up and running, so if you don't already
have a sever you can use for testing, see the full instructions for setting up
a farmOS Docker container.
If you wish to proxy an address other than
http://localhost:80, you'll need to
change the proxy settings in
dev.proxy.target to the address and port of your farmOS testing server.
Restart the devServer and it should now be proxying your new address. It may
also be necessary to add new endpoints to the
dev.proxy.context array as new
features are developed and new endpoints on the farmOS server need to be
reached. For more information, see the Webpack documentation on configuring the
You will also need to configure the server to enable CORS requests. Go to
http://localhost/admin/config/farm/access and enter
as the Access-Control-Allow-Origin.
Finally, when logging in to the client from the browser, simply leave the URL field blank. The devServer will then interpret all requests as relative links and proxy them accordingly. For some reason login can sometimes fail on the first attempt, but should succeed on all subsequent attempts.
- Cordova docs on running the emulator and debugger in Android Studio
- Cordova docs on running the emulator and debugger in XCode
Web build process¶
To build the client for the web, you just need to run the build script:
$ npm run build:web
The output of this script will be found in the
dist directory and can be
deployed using web server.
Native build process¶
To build from source, you'll need to clone the client repository from GitHub:
$ git clone https://github.com/farmOS/farmOS-client.git
Bundling the web assets with Webpack is fairly straight-forward. Node
(v.6.0.0 or higher) and npm (v.3.0.0 or higher) are the only system
dependencies with npm, which is automatically included with Node. The npm
build:native can then run Webpack to bundle the assets. All this can
be done by running the following two commands from the project's root
$ npm install $ npm run build:native
This will generate all the necessary files within the
www directory, which
Webpack will create if it doesn't already exist. Do not alter these files
directly. They are optimized for WebView, which is basically a browser that
Cordova installs and runs inside the native application itself to render all
and Android implementations
All the web assets are now ready for building the final native packages. Both platforms will require installing Cordova globally, via npm:
$ npm install -g cordova
This, however, is where the process diverges into separate iOS and Android builds. This next stage will probably comprise the most system configuration, too, since it requires installing each platform's SDK (Software Development Kit), if they aren't installed already. Of course, if you only intend to build for one platform, you only need to install that platform's SDK and corresponding system requirements; building for both platforms will require installing both SDK's.
To configure your system to build the Android app, follow Cordova's Android Platform Guide" and the Android Studio installation guide. This will differ depending on your development machine's operating system, but Mac, Windows and Linux are all supported.
- Java 8
- Android Studio
Note that Android Studio recommends the official Oracle JDK for Java 8; using OpenJDK may cause errors. Also make sure to follow Cordova's instructions for setting up your system's environment variables and installing the SDK packages for the Android versions the app will target. As of May 2018, the latest version of Android that Cordova seems to support is 7.1.1, at API Level 25.
Once Android Studio is installed and configured, make sure Android has been added to Cordova's list of platforms, then you're try out the build command:
$ cordova platform add android $ cordova build android
By default, the
build command will produce a debugging APK (equivalent to
cordova build android --debug). If you want to build a final release
version, you'll need to add the
--release flag, but you'll also need to use
your keys for signing the APK (see "Signing an App" in the Cordova docs for
more details). For reference, the official farmOS Field Kit app is built using
the following flags:
cordova build android --release -- \ --keystore=/path/to//your-key.keystore \ --storePassword=xxxxxxxx \ --alias=yyyy --password=zzzzzzzz
Both the debug and release APK's can then be found at
path/to/farmOS-client/platforms/android/app/build/outputs/apk after building.
Only available on Apple OS X. Windows and Linux are not supported. For some workarounds, see "Developing an iOS App on Linux"
You'll need Xcode installed in order to run the Cordova build commands. See Cordova's iOS Platform Guide for more info.
Once you have the environment set up, you'll want to add the iOS platform with Cordova (we recommend version 5.1.1 or higher), then you can run a debugging build:
cordova platform add firstname.lastname@example.org cordova build ios
build command without the
--release flag triggers a debug build
by default. To build a signed app for the App Store, you'll need to follow
Cordova's app signing guidelines, but for reference, we use the following
command and flags:
cordova build ios --release --device \ --codeSignIdentity="iPhone Distribution" \ --developmentTeam="ABCD1234" \ --packageType="app-store" \ --provisioningProfile="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
Signed .ipa files will be found at