Add configuration for Docker based development environment

This patch introduces a simple docker-compose based development environment
with the idea to allow most development use cases for beginning and
experienced MediaWiki developers.

- PHP and Apache container with XDebug enabled
- Support for overriding services with docker-compose override file
- Documentation for usage and a documented place for sharing docker-compose
  overrides and LocalSettings.php configuration snippets for e.g. MySQL,
	DB replication, Redis, etc

Depends-On: I50079cca6a286d8aaea8fd0785be48c80e80271c
Bug: T238224
Change-Id: I3b76c1599b1ff32174af5603aadc9f7c7634c98b

.gitattributes

@@ -11,3 +11,5 @@ README.mediawiki export-ignore
 Gemfile* export-ignore
 vendor/pear/net_smtp/README.rst export-ignore
 phpunit.xml.dist export-ignore
+DEVELOPERS.md export-ignore
+docker-compose.yml export-ignore

.gitignore

@@ -87,3 +87,6 @@ Thumbs.db
 /.htpasswd
 /tests/phan/issues
 *.rej
+
+# Docker
+docker-compose.override.yml

DEVELOPERS.md

@@ -0,0 +1,215 @@
+# MediaWiki Developers
+
+Welcome to the MediaWiki community! Please see [How to become a MediaWiki
+hacker](https://www.mediawiki.org/wiki/How_to_become_a_MediaWiki_hacker) for
+general information on contributing to MediaWiki.
+
+## Docker Developer Environment
+
+MediaWiki provides an extendable local development environment based on
+Docker Compose.
+
+The default environment provides PHP, Apache, XDebug and a SQLite database.
+(**Do not run this stack in production! Bad things might happen!**)
+
+More documentation is available at [mediawiki.org/wiki/Docker][mw-docker]
+and example overrides and configuration recipes are available at
+[mediawiki.org/wiki/Docker/Recipes][mw-docker-recipes].
+
+Support is available on the [Freenode IRC network][freenode] at `#mediawiki`
+and on Wikimedia Phabricator at [#MediaWiki-Docker][mw-docker-phab].
+
+[mw-docker]: https://www.mediawiki.org/wiki/Docker
+[mw-docker-recipes]: https://www.mediawiki.org/wiki/Docker/Recipes
+[mw-docker-phab]: https://phabricator.wikimedia.org/project/profile/3094/)
+[freenode]: https://freenode.net/
+
+### Requirements
+
+You'll need a locally running Docker and Docker Compose:
+
+  - [Docker installation instructions][docker-install]
+  - [Docker Compose installation instructions][docker-compose]
+
+[docker-install]: https://docs.docker.com/install/
+[docker-compose]: https://docs.docker.com/compose/install/
+
+### Quickstart
+
+#### MacOS & Windows prerequisites
+
+Hopefully, this should Just Work™.
+
+#### Linux prerequisites
+
+If you are developing on a Linux system, first create a
+`docker-compose.override.yml` containing the following:
+
+```yaml
+version: '3.7'
+services:
+  mediawiki:
+    # On Linux, these lines ensure file ownership is set to your host user/group
+    user: "${UID}:${GID}"
+```
+
+Next, ensure that `$UID` and `$GID` are set in your environment:
+
+```
+export UID=$(id -u)
+export GID=$(id -g)
+```
+
+The above lines may be added to your `.bashrc` or other shell configuration.
+
+#### Start environment and install MediaWiki
+
+Start the environment:
+
+```sh
+# -d is detached mode - runs containers in the background:
+docker-compose up -d
+```
+
+Install Composer dependencies:
+
+```sh
+docker-compose exec mediawiki composer update
+```
+
+Install MediaWiki in the environment:
+
+```sh
+docker-compose exec mediawiki \
+bash -c 'php maintenance/install.php \
+--server $MW_SERVER \
+--scriptpath=$MW_SCRIPTPATH \
+--dbtype $MW_DBTYPE \
+--dbpath $MW_DBPATH \
+--lang $MW_LANG \
+--pass $MW_PASS \
+$MW_SITENAME $MW_USER'
+```
+
+##### Re-install
+
+Remove or rename `LocalSettings.php`, delete the `cache/sqlite` directory, then
+re-run the installation command above. Copy over any changes from your previous
+`LocalSettings.php` and then run `maintenance/update.php`.
+
+### Usage
+
+#### Running commands
+
+You can use `docker-compose exec mediawiki bash` to open a bash shell in the
+MediaWiki container, or you can run commands in the container from your host,
+for example: `docker-compose exec mediawiki php maintenance/update.php`
+
+#### Running tests
+
+##### PHPUnit
+
+Run all tests:
+
+```sh
+docker-compose exec mediawiki php tests/phpunit/phpunit.php
+```
+
+Run a single test:
+
+```sh
+docker-compose exec mediawiki php tests/phpunit/phpunit.php /path/to/test
+```
+
+See [PHPUnit Testing][phpunit-testing] on MediaWiki.org for more help.
+
+[phpunit-testing]: https://www.mediawiki.org/wiki/Manual:PHP_unit_testing/Running_the_unit_tests
+
+##### Selenium
+
+You can use [Fresh][fresh] to run [Selenium in a dedicated
+container][selenium-dedicated]. Example usage:
+
+```sh
+export MW_SERVER=http://localhost:8080
+export MW_SCRIPT_PATH=/
+export MEDIAWIKI_USER=Admin
+export MEDIAWIKI_PASSWORD=dockerpass
+fresh-node -env -net
+npm ci
+npm run selenium
+```
+
+[selenium-dedicated]: https://www.mediawiki.org/wiki/Selenium/Node.js/Target_Local_MediaWiki_(Container)
+
+#### API Testing
+
+You can use [Fresh][fresh] to run [API tests in a dedicated
+container][api-dedicated]. Example usage:
+
+```sh
+export MW_SERVER=http://localhost:8080/
+export MW_SCRIPT_PATH=/
+export MEDIAWIKI_USER=Admin
+export MEDIAWIKI_PASSWORD=dockerpass
+fresh-node -env -net
+# Create .api-testing.config.json as documented on
+# https://www.mediawiki.org/wiki/MediaWiki_API_integration_tests
+npm ci
+npm run api-testing
+```
+
+[fresh]: (https://github.com/wikimedia/fresh
+[api-dedicated]: https://www.mediawiki.org/wiki/MediaWiki_API_integration_tests
+
+### Modifying the development environment
+
+You can override the default services with a `docker-compose.override.yml`
+file, and configure those overrides with changes to `LocalSettings.php`.
+Example overrides and configurations can be found at
+https://www.mediawiki.org/wiki/Docker
+
+After updating `docker-compose.override.yml`, run `docker-compose down`
+followed by `docker-compose up -d` for changes to take effect.
+
+#### Installing extra packages
+
+If you need root on the container to install packages for troubleshooting,
+you can open a shell as root with `docker-compose exec --user root mediawiki
+bash`.
+
+#### XDebug
+
+You can override the XDebug configuration included with the default image by
+passing `XDEBUG_CONFIG={your config}` in `environment`:
+
+``` yaml
+version: '3.7'
+services:
+  mediawiki:
+    environment:
+      XDEBUG_CONFIG: remote_enable=1 remote_host=172.17.0.1 remote_log=/tmp/xdebug.log remote_port=9009
+```
+
+##### Troubleshooting
+
+###### Port conflicts
+
+If you installed php-fpm on your host, that is listening on port 9000 and
+will conflict with XDebug. The workaround is to tell your IDE to listen on a
+different port (e.g. 9009) and to set the configuration in your
+`docker-compose.override.yml` file: `XDEBUG_CONFIG: remote_port=9009`
+
+###### Linux desktop, host not found
+
+The image uses `host.docker.internal` as the `remote_host` value which
+should work for Docker for Mac/Windows. On Linux hosts, you need to specify
+the hostname or IP address of your host. The IP address works more reliably.
+You can obtain it by running e.g. `ip -4 addr show docker0` and copying the
+IP address into the config, like `XDEBUG_CONFIG: remote_host=172.17.0.1`
+
+###### Generating logs
+
+Switching on the remote log for XDebug comes at a performance cost so only
+use it while troubleshooting. You can enable it like so: `XDEBUG_CONFIG:
+remote_log=/tmp/xdebug.log`

RELEASE-NOTES-1.35

@@ -90,6 +90,9 @@ For notes on 1.34.x and older releases, see HISTORY.
 * …
 
 === New developer features in 1.35 ===
+* A Docker based local development develpoment environment configuration is
+  included (T238224) and DEVELOPERS.md has been added with usage documentation
+  and links to further help.
 * If CSP is enabled, extensions can now add additional sources using the
   ContentSecurityPolicy::addDefaultSource, ::addStyleSrc and ::addScriptSrc
   methods (e.g. $context->getOutput()->getCSP()->addDefaultSrc( 'example.com' ))

docker-compose.yml

@@ -0,0 +1,24 @@
+# Please see DEVELOPERS.md for help
+#
+# Contributions to this file are welcome but please note that this file is
+# minimal by design, with the idea to make it easily extensible via
+# docker-compose.override.yml. For help with doing that, please see
+# DEVELOPERS.md
+version: '3.7'
+services:
+  mediawiki:
+    image: docker-registry.wikimedia.org/dev/stretch-php72-fpm-apache2-xdebug:0.0.3
+    ports:
+      - "8080:8080"
+    volumes:
+      - ./:/var/www/html:cached
+    environment:
+      COMPOSER_CACHE_DIR: '/var/www/html/cache/composer'
+      MW_SERVER: 'http://localhost:8080'
+      MW_SCRIPT_PATH: ''
+      MW_DBPATH: '/var/www/html/cache/sqlite'
+      MW_DBTYPE: 'sqlite'
+      MW_LANG: 'en'
+      MW_USER: 'admin'
+      MW_PASS: 'dockerpass'
+      MW_SITENAME: 'MediaWiki'