MediaWiki-Docker

MediaWiki-Docker is a Docker based development environment included with MediaWiki core.

Quickstart

Installing the dependencies and setting up the environment should take about 15 minutes

• Clone the MediaWiki core repository: git clone --depth=1 https://gerrit.wikimedia.org/r/mediawiki/core.git mediawiki
• Follow the directions in DEVELOPERS.md in the root of the mediawiki repository
• Optional: extend the environment using the configuration recipes listed below

Support

If you run into issues, here are ways to get help.

• For a quick question, use #mediawiki ^connect.
• Feature requests and bug reports can be filed at MediaWiki-Docker.
• For discussions, please use mail:wikitech-l.

Tutorials / Guides

Guides for setting up specific extensions or sets of extensions

• GrowthExperiments
• TwoColConflict
• WikibaseMediaInfo

Configuration recipes

Below are configuration recipes that can be used with MediaWiki core's Docker development environment.

docker-compose stacks can be extended with a docker-compose.override.yml file that resides in the same directory (at the root of MediaWiki core, in our case) as the docker-compose.yml file. Any configuration present in that file will override the defaults in docker-compose.yml. More documentation on overriding works is available at https://docs.docker.com/compose/extends/

After updating your override file, run docker-compose down followed by docker-compose up -d.

Example docker-compose.override.yml file

Below is a complete override file that provides a Redis and ElasticSearch containers, along with overriding the user mapping and the XDebug configuration for the app container.

version: '3.7'
services:
  mediawiki:
    # On Linux, these lines ensure file ownership is set to your host user/group
    user: "${MW_DOCKER_UID}:${MW_DOCKER_GID}"
    environment:
      # On Linux, replace "yourhostname" with the output of `hostname`
      XDEBUG_CONFIG: remote_host=yourhostname

  # Note, adding a redis service requires changes to LocalSettings.php to work.
  redis:
    image: redis

  # Note, adding an elasticsearch service requires changes to LocalSettings.php to work.
  elasticsearch:
    image: elasticsearch:6.8.2
    environment:
      - discovery.type=single-node
    ports:
      - '9200:9200'
      - '9300:9300'
    volumes:
      - esdata:/usr/share/elasticsearch/data

volumes:
  esdata:
    driver: local

Enable development settings

You probably want to enable MediaWiki's development settings. Log files will be generated in cache/mw-error.log and cache/mw-debug-www.log.

LocalSettings.php

$wgCacheDirectory = "$IP/cache";
require_once "$IP/includes/DevelopmentSettings.php";

Disable XDebug for better performance

If you are not working on backend code or don't need to set breakpoints, you can use a Docker image that has XDebug disabled, which can boost performance.

docker-compose.override.yml

version: '3.7'
services:
  mediawiki:
    image: docker-registry.wikimedia.org/dev/stretch-php72-fpm-apache2

Mail handling

You can capture outgoing email with MailHog. The mail interface is accessible at http://localhost:8025/

docker-compose.override.yml

version: '3.7'
services:
  mail:
    image: mailhog/mailhog
    ports:
    - "8025:8025"

LocalSettings.php

$wgSMTP = [
    'host'     => 'mail',
    'IDHost'   => 'mail',
    'port'     => '1025',
    'auth'     => false,
];

ElasticSearch

docker-compose.override.yml

version: '3.7'
services:
  elasticsearch:
    image: docker-registry.wikimedia.org/dev/stretch-elasticsearch:0.0.1
    volumes:
      - esdata:/usr/share/elasticsearch/data
    environment:
      - discovery.type=single-node
volumes:
  esdata:
    driver: local

LocalSettings.php

wfLoadExtension( 'CirrusSearch' );
require_once "$IP/extensions/CirrusSearch/tests/jenkins/FullyFeaturedConfig.php";
$wgCirrusSearchServers = [ 'elasticsearch' ];

Setup commands

# Installs the dependencies for Elastica
docker-compose exec mediawiki composer --working-dir=/var/www/html/extensions/Elastica install 
# Configure the search index and populate it with content
docker-compose exec mediawiki php extensions/CirrusSearch/maintenance/updateSearchIndexConfig.php
docker-compose exec mediawiki php extensions/CirrusSearch/maintenance/forceSearchIndex.php --skipLinks --indexOnSkip
docker-compose exec mediawiki php extensions/CirrusSearch/maintenance/forceSearchIndex.php --skipParse
# Process the job queue. You need to do this any time you add/update content and want it updated in ElasticSearch
docker-compose exec mediawiki php maintenance/runJobs.php

EventLogging

docker-compose.override.yml

version: '3.7'
services:
  eventlogging:
    image: docker-registry.wikimedia.org/dev/eventlogging:0.0.1
    ports:
      - "8100:8100"

LocalSettings.php

wfLoadExtension( 'EventLogging' );
$wgEventLoggingBaseUri = 'http://eventlogging:8100/event.gif';

Setup commands

1. Clone the Extension:EventLogging extension into extensions/EventLogging
2. You can tail the output to the eventlogging container with docker logs -f $(docker-compose ps -q eventlogging), or, pipe it to jq with docker logs -f $(docker-compose ps -q eventlogging) | jq
3. For client-side logging to work properly, you need to modify your system's /etc/hosts file with an entry that looks like this: 127.0.0.1 eventlogging
   

Ngrok

You can use ngrok to share your local site with others. After installing ngrok, run ngrok http 8080. Whatever URL is shown to you needs to be set in your LocalSettings.php.

LocalSettings.php

if ( isset( $_SERVER['SERVER_NAME'] ) && strpos( $_SERVER['SERVER_NAME'], 'ngrok' ) > 0 ) {
	$wgServer = WebRequest::detectProtocol() . '://' . $_SERVER['SERVER_NAME'];
}

Performance profiling with XHProf

You can use XHProf to profile requests.

docker-compose.override.yml

TODO: Adapt something from https://github.com/perftools/xhgui/blob/master/docker-compose.yml

LocalSettings.php

// Change to `true` when you want to profile a request.
if ( false ) {
	$wgProfiler['class'] = ProfilerXhprof::class;
	$wgProfiler['flags'] = TIDEWAYS_XHPROF_FLAGS_NO_BUILTINS;
	$wgProfiler['output'] = [ 'ProfilerOutputDump' ];
	$wgProfiler['outputDir'] = sys_get_temp_dir();
}