MediaWiki-Docker

From MediaWiki.org
Jump to navigation Jump to search

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

Drawing of the bowhead whale.gif
Quickstart
Installing the dependencies and setting up the environment should take about 15 minutes
Help icon (the Noun Project 38716).svg
Support
If you run into issues, here are ways to get help.
Noun spore 153131
Tutorials / Guides
Guides for setting up specific extensions or sets of extensions
Documents icon - noun project 5020
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[edit]

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[edit]

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[edit]

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[edit]

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[edit]


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[edit]

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[edit]

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[edit]

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();
}