farmOS
Demo farmOS

Installing farmOS

These instructions are for installing farmOS on a live production server. For local development/testing, please refer to the development environment documentation.

Server requirements

farmOS is based on Drupal, and therefore shares many of the same requirements.

Web server

In addition to Drupal's basic requirements, farmOS has the following server dependencies. The farmOS Docker images include these.

  • PHP 8+
  • PHP configuration - The following PHP settings are recommended:
    • memory_limit=256M
    • max_execution_time=240
    • max_input_time=240
    • max_input_vars=5000
    • realpath_cache_size=4096K
    • realpath_cache_ttl=3600
  • PHP BCMath extension and GEOS are required for accurate geometric calculations. farmOS can be installed without these, but production usage without them is strongly discouraged.

Database server

A database server needs to be provisioned that farmOS can connect to. PostgreSQL is recommended. MySQL/MariaDB and SQLite are also supported.

This can be installed on the same server as farmOS (either directly or in a Docker container), or it can be on a separate server.

If PostgreSQL is used, it must be version 12 or higher, and the pg_trgm extension must be installed and enabled on the farmOS database. On PostgreSQL 13+ this will be enabled automatically by farmOS. On PostgreSQL 12, the following SQL query must be run on the farmOS database by a PostgreSQL superuser to enable the extension:

CREATE EXTENSION pg_trgm;

SSL

Although not strictly a requirement, some features (like the "Geolocate" button on maps) will only work over a secure connection. Field Kit requires SSL in order to connect to it. SSL is also recommended if you are streaming sensor data into farmOS, to keep your sensor's private key a secret.

A common strategy is to use Nginx as a reverse proxy with SSL termination, which listens on port 443 and forwards to farmOS on port 80. Let's Encrypt is a good option for free SSL certificate issuance, and renewal can be automated via cron.

These resources may be helpful:

  • Drupal HTTPS Information
  • Reverse Proxy Forum Post - Includes links to related GitHub issues and examples of how others have configured reverse proxies serving HTTPS.
  • Local HTTPS - Documentation for running an Nginx reverse proxy with self-signed certificates for local farmOS development with HTTPS.

Satellite map layers

farmOS includes an optional Mapbox module that can be enabled to add satellite imagery layers to the map. A Mapbox API key is required. For more information, see Mapbox's official documentation: Access tokens. Enable the Mapbox module at Setup > Modules, and then add the API key at Setup > Settings > Map > Mapbox.

farmOS Codebase

There are two supported approaches to deploying the farmOS codebase:

  1. Using Docker images.
  2. Using packaged releases.

Docker is the recommended method of hosting farmOS because it encapsulates the server level dependencies that farmOS needs.

If you need to build a more customized farmOS codebase, including modules provided by the community, or custom modules written by yourself, see Building farmOS with Composer.

farmOS in Docker

Official farmOS Docker images are available on Docker Hub: https://hub.docker.com/r/farmos/farmos

This allows farmOS to be run in a Docker container with:

docker pull farmos/farmos:3.x.y
docker run --rm -p 80:80 -v "${PWD}/sites:/opt/drupal/web/sites" farmos/farmos:3.x.y

Replace 3.x.y with the desired version. Find the latest farmOS version on the GitHub release page. Using the latest Docker tag is not recommended, because updates require manual steps. See Updating farmOS for more info.

This will pull the farmOS Docker image, provision a farmOS web server container listening on port 80, and bind-mount a sites directory into the container for persistence of settings and uploaded files.

Docker Compose

Docker Compose can be used to encapsulate these decisions.

An example docker-compose.production.yml configuration file is provided in the farmOS repository's docker directory, with an accompanying README.md. Copy this to a file named docker-compose.yml in the directory you would like to install farmOS, update the farmos/farmos:x.y.z version reference, and run:

docker compose up -d

Persistence

All site-specific settings and user-uploaded files are stored in /opt/drupal/web/sites inside the container, so it is important that the contents of this directory be persisted outside of the container. Bind-mounting a directory from the host into the container is the recommended way to achieve this.

The docker run command above does this, as well as the example docker-compose.yml provided in the farmOS repository's docker directory.

If the sites directory is not persisted, all settings and files will be lost when the container is destroyed, and you will be prompted to install farmOS again when a new container is started.

Customizing PHP

If customizations to PHP's configuration are required, such as increasing the maximum upload size limit, you can bind-mount a custom PHP settings file into the container.

Create a file called php.ini alongside docker-compose.yml:

upload_max_filesize = 50M
post_max_size = 50M

Bind-mount php.ini into the www service in your docker-compose.yml file:

    volumes:
      ...
      - './php.ini:/usr/local/etc/php/conf.d/farmos.ini'

Packaged releases

An alternative to the Docker-based deployment is to install the farmOS codebase directly on the host server using a packaged release tarball, available from GitHub: github.com/farmOS/farmOS/releases

Packaged releases include everything from the /opt/drupal directory in the Docker image. This represents the entire farmOS codebase, pre-built with Composer.

Download and unpack the tarball on your web server, and point the document root at the web subdirectory.

Installing farmOS

Once you have the farmOS codebase deployed, and a database server provisioned, you can proceed with the web-based farmOS installation. Visit the farmOS server's hostname in your browser and follow the steps to install farmOS and optional modules.

File uploads

In order to upload files, a private filesystem path must be configured in the settings.php file after installation is complete.

If you are using the official Docker image, and bind-mounting the sites directory as a volume, add the following line to sites/default/settings.php:

$settings['file_private_path'] = '/opt/drupal/web/sites/default/private/files';

Additionally, create the folder /opt/drupal/web/sites/default/private/.

Set the correct user and permissions:

Folder ownership and group should match the web server user. If you are using the farmOS Docker image (running Apache), this will be www-data.

Folder permissions should be set to 770 or drwxrwx---.

If you are using a packaged release outside of Docker, replace /opt/drupal/web with the path to the webroot directory that contains your sites directory.

Finally, make sure to clear the caches by visiting Administration > Configuration > Development > Performance and clicking the Clear all caches button, or use Drush via the command line: drush cr.

Cron

farmOS performs routine tasks via its built-in cron. This includes database cleanup and garbage collection. A cron job must be configured on the host system to trigger this. There are three ways to do this:

1. Via the drush cron command (recommended)

The Drush command-line tool provides a cron command for triggering the execution of cron tasks. This can be run via a scheduled system crontab. Weekly is enough for most use-cases.

The actual drush command will vary depending on how/where you have farmOS installed. Drush is located in vendor/bin/drush within the farmOS codebase, and may require additional arguments to find your farmOS database correctly. For more information, see the Drush cron documentation.

If you are running farmOS in the official Docker container, your crontab will look something like this (replace [container-name] with the name of your running farmOS container):

4 0 * * 0 sudo docker exec -it -u www-data [container-name] drush cron > /dev/null

2. Via the secret cron URL

A special URL is available for running cron via an HTTP request. This URL includes a secret key to prevent it from being run by unauthorized requests. To find the secret cron URL, while logged in as a farmOS administrator, go to Administration > Configuration > System > Cron. The URL will look like this:

https://[base-url]/cron/[secret-key]

Use wget in a Linux cron job to request this URL on a schedule. Weekly is enough for most use-cases.

4 0 * * 0 wget -O - -q -t 1 [cron-url] > /dev/null

The only disadvantage of this approach is it may run into PHP memory_limit or max_execution_time restrictions, if the cron tasks are particularly long or complex.

3. Via the "Automated Cron" module (not recommended)

Drupal also includes an "Automated Cron" module, which is disabled by default in farmOS. When enabled, this module will automatically perform cron tasks at the end of normal visitor requests. This option is only recommended if your host system does not have the ability to configure cron jobs. It can cause random requests to farmOS to be very slow, as the cron tasks are tacked onto the normal page loading process.