How to install a custom FarmOS module

FarmOS

I’ve recently ventured into the realm of creating a home server, mainly to play around with a Linux operating system (I’ve only ever used Windows) and self-host some programs using Docker containers. Nothing major – I’ve purchased a cheap, refurbished SFF (“slim form factor”) computer for $50 from eBay and installed Ubuntu.

My family has a small farmette in central Virginia and, in my perusal of the Awesome Self Hosting list on GitHub, I found a neat program called farmOS. While mostly overkill for my needs, it interfaces with a PostgreSQL and PostGIS database, allowing me to keep track of the amount of eggs from our chickens and geese, in which fields we’re grazing the pigs, and more, all in a spatially-explicit manner! It is also open source, and built around the idea of custom extensibility using “modules”.

Drupal Modules

farmOS is built using Drupal, an open-source back end used by a whole bunch of web sites. Drupal allows extending their sites using the modules mentioned above.

In fact, what originally drew me to the idea of running this program was mapping the assets in my farm onto satellite imagery. This is possible through using a module to access satellite imagery from Mapbox or Google. However, I couldn’t find out how to make the Google satellite images show up – all of my searching led to exchanges like this:

Person 1: How do I get Google satellite images to appear?
Person 2: Did you install the module?
Person 1: I just did and it works! Thanks!

The whole thing felt a little bit like the underpants gnomes – I had no idea how to get from step 2 to step 3.

Nominally, the whole thing operates using Drupal; I had no idea what Drupal was as I was coming from a non-computer-mostly-ecology background. To make matters more confusing, there are a few points where the FarmOS developers attempt to steer you away from using canned Drupal add-ons. To make matters EVEN MORE confusing, I am deploying FarmOS in a Docker container which means that the standard instructions to install modules that are provided by Drupal don’t necessarily apply.

Git to the rescue

Luckily the developers are very open, communicative, and welcoming on their Discord channel. Following this question, wherein they reinforced the idea of cloning a GitHub repository, and their module outline, where they provide some best practices, I was able to piece together my own workflow. The following assumes that you are accessing your FarmOS instance via the command line.

First, change your directory to the www folder. My FarmOS Docker container is located in a directory called farmos, which contains my docker-compose.yaml file and the www directory.

cd farmos/www

Next, create a directory called all with a subdirectory called modules. The FarmOS module development guide suggests separate subdirectories for general-purpose modules and those specific to your farm, but I’m not sure I’m going to get that deep into development so I’m skipping that stage.

mkdir -p all/modules

Now find the GitHub repository (or Gitlab, or whatever flavor of git host you prefer) and clone it into the www/all/modules directory. I really wanted to use Google satellite imagery over Mapbox as the images were more up-to-date, so I selected Symbioquine’s fork of the Google Farm Map module.

cd all/modules
git clone https://github.com/symbioquine/farm_map_google.git

Now the module can be found by your FarmOS GUI and then be installed.

Install the module

To finish installing the module, log into FarmOS. Click the settings gear, then extend, then search for the module’s name in the filter bar. Click “Install”, and you’re done!

Google API

Part of the reason that FarmOS doesn’t ship with the Google satellite module already installed is because Google frequently changes their API and the developers wanted to focus elsewhere. Very fair. In fact, after installing this module and going through the rigmarole of attaining and entering an API key, I still couldn’t get the module to work.

Next steps: Making your own module

So, here I am with Mapbox working but not updated in the past three years, Google not working and also not updated in the last year, and a farm that has had substantial updates over the last few months. What am I to do?

Luckily, the Commonwealth of Virginia and my locality both provide recent satellite imagery to the public. In addition to the Google Maps addon, Symbioqiune had created a module to use the San Juan Islands’ provided imagery. I’ll parse out how that works and adapt it to Virginia’s imagery in my next blog post.