# Installation

farmOS is a [Drupal distribution], so it is essentially a [Drupal] codebase that
combines [Drupal core] with a set of pre-selected contributed modules.

## Recomended release

The recommended approach is to download the latest release of the pre-packaged
[farmOS distribution] from Drupal.org.

The Drupal.org packaged release is pre-built and ready to go. Just drop it into
a hosted web server environment and it will work the same as Drupal. For more
information on installing Drupal, see the official [Drupal Installation Guide].

## Local development

See [farmOS on Docker].

## Requirements

You will need a web server with all the basic [requirements of Drupal].

In addition to Drupal's basic requirements, farmOS also needs the following:

* **PHP 7+**
* **PHP configuration** - It is recommended that you set the following PHP
  configuration variables, to ensure that farmOS runs smoothly. It may run fine
  without these settings, but some features may not work properly without them.
  Note that the farmOS [Docker] image sets these automatically.
    * `memory_limit=256M`
    * `max_execution_time=240`
    * `max_input_time=240`
    * `max_input_vars=5000`
* **Drupal configuration** - Clean URLs must be enabled in Drupal. Check the 
  configuration on the Drupal configuration page 
  *(Administration > Configuration > Search and metadata > Clean URLs)* and 
  enable Clean URLs. If running Apache web-server, `mod_rewrite` must be enabled. 
  For additional instructions, see the [Enable clean URLs] page in Drupal Documentation.

### Optional dependencies

The following are not hard requirements of farmOS, but will provide progressive
enhancements if they are available.

* **Google Maps and/or MapBox API keys** are necessary for rendering the Google
  Maps and MapBox base layers in farmOS maps. See the [API keys] instructions
  for more information about how to set this up. If API keys are not provided,
  [OpenStreetMap] will be used as the default base layer.
* **[PHP BCMath extension]** is required for accurate geometric polygon area
  calculations.
* **[GEOS - Geometry Engine, Open Source]** is required by the Area Generator
  module.
* **SSL** Although not strictly a requirement, some features (like the
  "Geolocate" button on maps) will only work when over a secure connection.
  [Field Kit] requires SSL on your farmOS instance in order to connect to it.
  SSL is also recommended if you are using the Sensor Listener module to keep
  your sensor's private key a secret. These resources may be helpful for 
  configuring SSL:
    * [Drupal HTTPS Information]
    * [Reverse Proxy Forum Post] - Includes links to related GitHub issues and 
    examples of how others have configured reverse proxies forcing HTTPS.
    * [Configuring a Local Https Reverse Proxy] - Documentation on configuring
    SSL for local development.

[Drupal distribution]: https://drupal.org/documentation/build/distributions
[Drupal]: https://drupal.org
[Drupal core]: https://drupal.org/project/drupal
[https://drupal.org/project/farm]: https://drupal.org/project/farm
[farmOS distribution]: https://drupal.org/project/farm
[Drupal Installation Guide]: https://drupal.org/documentation/install
[farmOS on Docker]: /development/docker
[requirements of Drupal]: https://drupal.org/requirements
[Openlayers module]: https://drupal.org/project/openlayers
[Docker]: /development/docker
[API keys]: /hosting/apikeys
[OpenStreetMap]: https://www.openstreetmap.org
[PHP BCMath extension]: http://php.net/manual/en/book.bc.php
[GEOS - Geometry Engine, Open Source]: https://trac.osgeo.org/geos
[PostgreSQL]: https://www.postgresql.org
[PostGIS]: http://postgis.net
[GitHub issue #43]: https://github.com/farmOS/farmOS/issues/43
[Enable clean URLs]: https://www.drupal.org/docs/7/configuring-clean-urls/enable-clean-urls
[Field Kit]: /guide/app
[Drupal HTTPS Information]: https://www.drupal.org/https-information
[Reverse Proxy Forum Post]: https://farmos.discourse.group/t/running-behind-reverse-proxy/108
[Configuring a Local Https Reverse Proxy]: /development/configure-local-https-reverse-proxy
