253 lines
10 KiB
Markdown
253 lines
10 KiB
Markdown
# Installing farmOS
|
|
|
|
These instructions are for installing farmOS on a live production server.
|
|
For local development/testing, please refer to the
|
|
[development environment](/development/environment)
|
|
documentation.
|
|
|
|
## Server requirements
|
|
|
|
farmOS is based on [Drupal](https://drupal.org), and therefore shares many of
|
|
the same [requirements](https://drupal.org/docs/system-requirements).
|
|
|
|
### Web server
|
|
|
|
In addition to Drupal's basic requirements, farmOS has the following server
|
|
dependencies. The [farmOS Docker images](#farmos-in-docker) 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](https://www.php.net/manual/en/book.bc.php)** and
|
|
**[GEOS](https://trac.osgeo.org/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](https://farmOS.app)
|
|
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](https://nginx.org) as a reverse proxy with
|
|
SSL termination, which listens on port 443 and forwards to farmOS on port 80.
|
|
[Let's Encrypt](https://letsencrypt.org) is a good option for free SSL
|
|
certificate issuance, and renewal can be automated via cron.
|
|
|
|
These resources may be helpful:
|
|
|
|
- [Drupal HTTPS Information](https://www.drupal.org/https-information)
|
|
- [Reverse Proxy Forum Post](https://farmos.discourse.group/t/running-behind-reverse-proxy/108) -
|
|
Includes links to related GitHub issues and examples of how others have
|
|
configured reverse proxies serving HTTPS.
|
|
- [Local HTTPS](/development/environment/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](https://www.mapbox.com) 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](https://docs.mapbox.com/help/how-mapbox-works/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](https://docker.com) 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](/hosting/composer).
|
|
|
|
### farmOS in Docker
|
|
|
|
Official farmOS Docker images are available on Docker Hub:
|
|
[https://hub.docker.com/r/farmos/farmos](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](https://github.com/farmOS/farmOS/releases). Using the
|
|
`latest` Docker tag is not recommended, because updates require manual steps.
|
|
See [Updating farmOS](/hosting/update) 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](https://docs.docker.com/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](https://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](https://getcomposer.org).
|
|
|
|
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](https://www.drush.org/latest/cron).
|
|
|
|
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.
|