clean install

web/profiles/farm/docs/development/environment/code.md

@@ -0,0 +1,23 @@
+# Coding standards
+
+farmOS follows [Drupal coding standards](https://www.drupal.org/docs/develop/standards).
+
+The farmOS development Docker image comes pre-installed with
+[PHP CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) for detecting
+code standard violations, and [PHPStan](https://phpstan.org) for static
+analysis. All farmOS code must pass both.
+
+The following command will run PHP CodeSniffer on all farmOS code:
+
+    docker exec -it -u www-data farmos_www_1 phpcs /opt/drupal/web/profiles/farm
+
+If you see no output, then there are no issues.
+
+In some cases, code standard violations can be fixed automatically with
+`phpcbf`:
+
+    docker exec -it -u www-data farmos_www_1 phpcbf /opt/drupal/web/profiles/farm
+
+The following command will run PHPStan on all farmOS code:
+
+    docker exec -it -u www-data farmos_www_1 phpstan analyze /opt/drupal/web/profiles/farm

web/profiles/farm/docs/development/environment/composer.md

@@ -0,0 +1,42 @@
+# Composer
+
+The farmOS development Docker image comes pre-installed with
+[Composer](https://getcomposer.org), which is used for dependency management.
+
+## Running Composer in Docker
+
+In order to run the `composer` command, you must use `docker exec` to run the
+command inside the farmOS container.
+
+    docker exec -it -u www-data farmos_www_1 composer
+
+For example, the following will run the `composer help` command:
+
+    docker exec -it -u www-data farmos_www_1 composer help'
+
+**Warning**: If `composer update farmos/farmos` is run, it will replace the
+Git repository in `web/profiles/farm`, discarding all
+changes/branches/remotes/etc.
+
+## Common tasks
+
+Some common Composer tasks are documented here.
+
+### Adding a module
+
+    composer require drupal/[module]
+
+This will download the module into the `web/modules/contrib` directory, and add
+it to the root `composer.json` file.
+
+If the module is being added to the farmOS installation profile itself, you
+need to manually move the `require` line from the root `composer.json` to
+`web/profiles/farm/composer.json` and commit it to that repository.
+
+To install the module, use [Drush](/development/environment/drush).
+
+## Notes
+
+- `Could not delete /var/www/html/web/sites/default/default.settings.php`
+  See https://www.drupal.org/docs/develop/using-composer/starting-a-site-using-drupal-composer-project-templates#s-troubleshooting-permission-issues-prevent-running-composer
+

web/profiles/farm/docs/development/environment/debug.md

@@ -0,0 +1,39 @@
+# Debugging
+
+The farmOS development Docker image comes pre-installed with
+[XDebug](https://xdebug.org) 3, which allows debugger connections on port 9003.
+
+XDebug can be configured to discover the client host automatically with the
+following `extra_hosts` and `environment` configuration in `docker-compose.yml`:
+
+    extra_hosts:
+    - host.docker.internal:host-gateway
+    environment:
+      XDEBUG_MODE: debug
+      XDEBUG_CONFIG: client_host=host.docker.internal
+
+## PHPStorm
+
+If you are using the PHPStorm IDE, some additional environment variables are
+necessary:
+
+    XDEBUG_SESSION: PHPSTORM
+    PHP_IDE_CONFIG: serverName=localhost
+
+For example:
+
+    extra_hosts:
+    - host.docker.internal:host-gateway
+    environment:
+      XDEBUG_MODE: debug
+      XDEBUG_CONFIG: client_host=host.docker.internal
+      XDEBUG_SESSION: PHPSTORM
+      PHP_IDE_CONFIG: serverName=localhost
+
+With this configuration in place, enable the "Start listening for PHP Debug
+Connections" option. Add a breakpoint in your code, load the page in your
+browser, and you should see a prompt appear in PHPStorm that will begin the
+debugging session and pause execution at your breakpoint.
+
+This also works with command-line scripts like `drush`. You may need to map the
+path to Drush (`vendor/drush`) in the PHPStorm debugger config.

web/profiles/farm/docs/development/environment/docker.md

@@ -0,0 +1,37 @@
+# Docker
+
+## Docker build arguments
+
+The farmOS Docker images allow certain variables to be overridden at
+image build time using the `--build-arg` parameter of `docker build`.
+
+Available arguments and their default values are described below:
+
+- `FARMOS_REPO` - The farmOS Git repository URL.
+    - Default: `https://github.com/farmOS/farmOS.git`
+- `FARMOS_VERSION` - The farmOS Git branch/tag/commit to check out.
+    - Default: `3.x`
+- `PROJECT_REPO` - The farmOS Composer project Git repository URL.
+    - Default: `https://github.com/farmOS/composer-project.git`
+- `PROJECT_VERSION` - The farmOS Composer project Git branch/tag/commit to
+  check out.
+    - Default: `3.x`
+
+## Development image
+
+The `3.x-dev` image also provides the following build arguments:
+
+- `WWW_DATA_ID` - The ID to use for the `www-data` user and group inside the
+   image. Setting this to the ID of the developer's user on the host machine
+   allows Composer to create files owned by www-data inside the container,
+   while keeping those files editable by the developer outside of the
+   container. If your user ID is not `1000`, build the image with:
+   `--build-arg WWW_DATA_ID=$(id -u)`
+    - Default: `1000`
+
+To build the development image, it is necessary to add the `--target dev` flag
+to the `docker build` command.
+
+For example:
+
+`docker build --build-arg WWW_DATA_ID=$(id -u) -t farmos/farmos:3.x-dev --target dev docker`

web/profiles/farm/docs/development/environment/documentation.md

@@ -0,0 +1,38 @@
+# Documentation
+
+In addition to the code for farmOS, this repository includes the source files of the
+documentation which is hosted at [http://farmOS.org](http://farmos.org).
+
+It uses [mkdocs](http://www.mkdocs.org) to convert simple markdown files into
+static HTML files.
+
+To get started contributing to the farmOS documentation, fork
+[farmOS](https://github.com/farmOS/farmOS) on Github. Then install mkdocs and
+clone this repo:
+
+    $ brew install python                # For OSX users
+    $ sudo apt-get install python-pip    # For Debian/Ubuntu users
+    $ sudo pip install mkdocs mkdocs-material
+    $ git clone https://github.com/farmOS/farmOS.git farmOS
+    $ cd farmOS
+    $ git remote add sandbox git@github.com:<username>/farmOS.git
+    $ mkdocs serve
+
+Your local farmOS documentation site should now be available for browsing:
+http://127.0.0.1:8000/. When you find a typo, an error, unclear or missing
+explanations or instructions, hit ctrl-c, to stop the server, and start editing.
+Find the page you’d like to edit; everything is in the docs/ directory. Make
+your changes, commit and push them, and start a pull request:
+
+    $ git checkout -b fix_typo              # Create a new branch for your changes.
+    ...                                     # Make your changes.
+    $ mkdocs build --clean; mkdocs serve    # Go check your changes.
+    $ git diff                              # Make sure there aren’t any unintended changes.
+    ...
+    $ git commit -am "Fixed typo."          # Useful commit message are a good habit.
+    $ git push sandbox fix_typo             # Push your new branch up to your Github sandbox.
+
+Visit your fork on Github and start a Pull Request.
+
+For more information on writing and managing documentation with mkdocs, read the
+official mkdocs documentation: [http://www.mkdocs.org](http://www.mkdocs.org)

web/profiles/farm/docs/development/environment/drush.md

@@ -0,0 +1,28 @@
+# Drush
+
+The farmOS Docker image comes pre-installed with
+[Drush](https://www.drush.org), which provides shell commands for working with
+a Drupal installation.
+
+## Running Drush in Docker
+
+In order to run the `drush` command, you must use `docker exec` to run the
+command inside the farmOS container.
+
+    docker exec -it -u www-data farmos_www_1 drush
+
+For example, the following will run the `drush cr` command to rebuild caches:
+
+    docker exec -it -u www-data farmos_www_1 drush cr
+
+## Useful commands
+
+Some useful Drush commands are documented here.
+
+### Rebuild caches
+
+    drush cr
+
+### Install a module
+
+    drush en log

web/profiles/farm/docs/development/environment/https.md

@@ -0,0 +1,81 @@
+# Local HTTPS
+
+Some development testing is easier with farmOS on an `https://` endpoint.
+A separate [Nginx](https://nginx.com) reverse proxy provides a simple way to
+achieve this without any changes to the Apache configuration that runs in the
+farmOS Docker container.
+
+First, generate self-signed SSL certificate files into an `ssl` directory,
+from the directory that your `docker-compose.yml` file is in:
+
+```
+mkdir ssl
+openssl req -newkey rsa:4096 -x509 -sha256 -nodes -out ssl/openssl.crt -keyout ssl/openssl.key
+```
+
+Create a file called `nginx.conf` alongside `docker-compose.yml`:
+
+```
+events {}
+http {
+  server {
+      listen 80 default_server;
+      listen [::]:80 default_server;
+      server_name _;
+      return 301 https://$host$request_uri;
+  }
+  server {
+    server_name localhost;
+    listen 443 ssl;
+    ssl_certificate /etc/nginx/ssl/openssl.crt;
+    ssl_certificate_key /etc/nginx/ssl/openssl.key;
+    location / {
+      proxy_set_header Host $http_host;
+      proxy_set_header X-Real-IP $remote_addr;
+      proxy_set_header X-Forwarded-Host $http_host;
+      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+      proxy_set_header X-Forwarded-Proto $scheme;
+      proxy_buffer_size 128k;
+      proxy_buffers 4 256k;
+      proxy_busy_buffers_size 256k;
+      proxy_pass http://www;
+    }
+  }
+}
+```
+
+Add the following lines to `www/web/sites/default/settings.php`:
+
+```
+$settings['reverse_proxy'] = TRUE;
+$settings['reverse_proxy_addresses'] = [$_SERVER['REMOTE_ADDR']];
+$settings['reverse_proxy_trusted_headers'] = \Symfony\Component\HttpFoundation\Request::HEADER_X_FORWARDED_ALL;
+```
+
+Add the following service to your local `docker-compose.yml` file:
+
+```
+  proxy:
+    image: nginx
+    depends_on:
+      - www
+    ports:
+      - '80:80'
+      - '443:443'
+    volumes:
+      - './nginx.conf:/etc/nginx/nginx.conf'
+      - './ssl:/etc/nginx/ssl'
+```
+
+Also remove port 80 from the `www` service:
+
+```
+    ports:
+      - '80:80'
+```
+
+Finally, start the Docker services:
+
+`docker compose up`
+
+farmOS is now accessible via `https://localhost`.

web/profiles/farm/docs/development/environment/index.md

@@ -0,0 +1,71 @@
+# Getting started
+
+Follow these instructions to set up a local farmOS development environment.
+
+The only requirement is [Docker](https://www.docker.com).
+
+## 1. Set up Docker containers
+
+Run the following commands to create a farmOS directory and set up Docker
+containers for farmOS and PostgreSQL:
+
+    mkdir farmOS && cd farmOS
+    curl https://raw.githubusercontent.com/farmOS/farmOS/3.x/docker/docker-compose.development.yml -o docker-compose.yml
+    docker compose up -d
+
+## 2. Install farmOS
+
+Open `http://localhost` in a browser and install farmOS with the following
+database credentials:
+
+- Database type: **PostgreSQL**
+- Database name: `farm`
+- Database user: `farm`
+- Database password: `farm`
+- Advanced options > Host: `db`
+
+## 3. Develop
+
+After starting the Docker containers, the root `farmOS` directory will contain
+two new subdirectories: `www` and `db`.
+
+The `www` directory contains the fully built farmOS codebase, which is
+bind-mounted into the `www` container's `/opt/drupal` directory. The `www/web`
+directory is used as the Apache webroot. Loading the `www` directory in your
+favorite PHP IDE will provide easy code access to the full Symfony + Drupal +
+farmOS stack.
+
+The `db` directory contains the PostgreSQL database files, which is
+bind-mounted into the `db` container's `/var/lib/postgresql/data` directory.
+With the containers stopped, this directory can be backed up (eg: via tarball)
+to create snapshots for easy rollback during development.
+
+## Optional
+
+### Configure private filesystem
+
+In order to upload files, a private file path must be configured. The following
+line must be added to `www/web/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---`.
+
+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`.
+
+### Configure debugger
+
+See [Debugging](/development/environment/debug).
+
+### Enable HTTPS
+
+See [HTTPS](/development/environment/https).

web/profiles/farm/docs/development/environment/postgresql.md

@@ -0,0 +1,11 @@
+# PostgreSQL
+
+The farmOS Docker image comes pre-installed with the PostgreSQL client `psql`
+command, which can be used to connect to the database and run queries from
+the command line.
+
+## Open PostgreSQL prompt
+
+    docker exec -it farmos_www_1 psql -h db -d farm -U farm
+
+Enter `farm` as the password.

web/profiles/farm/docs/development/environment/tests.md

@@ -0,0 +1,63 @@
+# Automated tests
+
+The farmOS development Docker image comes pre-installed with all the
+dependencies necessary for running automated tests via
+[PHPUnit](https://phpunit.de).
+
+The following command will run all automated tests provided by farmOS:
+
+```sh
+docker exec -it -u www-data farmos_www_1 phpunit --verbose --debug /opt/drupal/web/profiles/farm
+```
+
+Tests from other projects/dependencies can be run in a similar fashion. For
+example, the following command will run all tests in the Log module:
+
+```sh
+docker exec -it -u www-data farmos_www_1 phpunit --verbose --debug /opt/drupal/web/modules/log
+```
+
+## Chrome/Selenium Container
+
+The PHPUnit tests depend on having Chrome/Selenium available at port 4444 and hostname "chrome".
+
+If using a docker-compose.yml based off [docker-compose.development.yml], this can be easily achieved
+by adding the following container:
+
+```yml
+  chrome:
+    # Tests are failing on later versions of this image.
+    # See https://github.com/farmOS/farmOS/issues/514
+    image: selenium/standalone-chrome:4.1.2-20220217
+```
+
+## Faster testing without XDebug
+
+The instructions above will run tests with XDebug enabled which may be helpful
+for [debugging](/development/environment/debug), but is also slower. XDebug can be disabled
+by setting the `XDEBUG_MODE` environment variable to "off".
+
+In a docker-compose.yml based off [docker-compose.development.yml], this might look like:
+
+```yml
+  www:
+    ...
+    environment:
+      ...
+      XDEBUG_MODE: 'off'
+```
+
+The tests could then be run via `docker compose exec` as follows:
+
+```sh
+docker compose exec -u www-data -T www phpunit --verbose --debug /opt/drupal/web/profiles/farm
+```
+
+Alternatively, the `XDEBUG_MODE` environment variable can be specified directly:
+
+```sh
+docker compose exec -u www-data -T --env XDEBUG_MODE=off www phpunit --verbose --debug /opt/drupal/web/profiles/farm
+```
+
+[run-tests.yml]: https://raw.githubusercontent.com/farmOS/farmOS/3.x/.github/workflows/run-tests.yml
+[docker-compose.development.yml]: https://raw.githubusercontent.com/farmOS/farmOS/3.x/docker/docker-compose.development.yml

web/profiles/farm/docs/development/environment/update.md

@@ -0,0 +1,44 @@
+# Updating local environment
+
+The following commands will update your local farmOS development environment.
+
+This approach avoids running `composer` commands because that is already done
+when the Docker image is built.
+
+**Warning**: This will replace everything except the `profiles` and `sites`
+directories. If you are developing farmOS core, this will ensure that your
+farmOS Git repository (inside `profiles/farm`) will not be touched. If you
+are developing a custom module, make sure that it is in `sites/all/modules`,
+otherwise it will be deleted.
+
+```
+# Run these commands from the local directory that contains docker-compose.yml.
+# The Docker containers should be running.
+
+# Backup www volume, just in case.
+sudo tar -czf www.tar.gz www
+
+# Pull latest 3.x-dev Docker image.
+docker pull farmos/farmos:3.x-dev
+
+# Move directories.
+mv www/web/profiles ./profiles
+mv www/web/sites ./sites
+
+# Update codebase.
+docker compose down
+rm -r www
+docker compose up -d
+
+# Restore directories.
+sudo rm -rf www/web/profiles www/web/sites
+mv ./profiles www/web/profiles
+mv ./sites www/web/sites
+
+# Update farmOS profile.
+cd www/web/profiles/farm
+git checkout 3.x && git pull origin 3.x
+
+# Run Drupal database updates.
+docker compose exec -u www-data www drush updb
+```