MediaWiki Developers

Welcome to the MediaWiki community! Please see How to become a MediaWiki hacker for general information on contributing to MediaWiki.

Development environment

MediaWiki provides an extendable local development environment based on Docker Compose. This environment provides PHP, Apache, Xdebug and a SQLite database.

Do not use the development environment to serve a public website! Bad things would happen!

More documentation, examples, and configuration recipes are available at mediawiki.org/wiki/MediaWiki-Docker.

Support is available on the Libera IRC network in the #mediawiki channel, and on Phabricator by creating tasks with the MediaWiki-Docker tag.

Quickstart

1. Requirements

You'll need to have Docker installed:

• Docker Desktop for macOS or Windows.
• docker and docker-compose for Linux.

Linux users:

• We recommend installing docker-compose by downloading the binary release. You can also use pip, your OS package manager, or even run it in a container, but downloading the binary release is the easiest method.
• Follow the instructions to "Manage Docker as a non-root user"

Windows users:

We recommend configuring Docker to use the Windows Subsystem for Linux (WSL) for performance improvements. If you do enable it, ensure the MediaWiki files in the next step are stored in the Linux filesystem, as described in the best practices page.

2. Download MediaWiki files

Download the latest MediaWiki files to your computer. One way to download the latest alpha version of MediaWiki is to install git, open a shell, navigate to the directory where you want to save the files, then type git clone https://gerrit.wikimedia.org/r/mediawiki/core.git mediawiki.

Optional: If you plan to submit patches to this repository, you will probably want to create a Gerrit account, then type git remote set-url origin ssh://YOUR-GERRIT-USERNAME-HERE@gerrit.wikimedia.org:29418/mediawiki/core, replacing YOUR-GERRIT-USERNAME-HERE with your Gerrit username. Please see the official MediaWiki Gerrit tutorial for more information.

3. Prepare .env file

Using a text editor, create a .env file in the root of the MediaWiki core repository, and copy these contents into that file:

MW_SCRIPT_PATH=/w
MW_SERVER=http://localhost:8080
MW_DOCKER_PORT=8080
MEDIAWIKI_USER=Admin
MEDIAWIKI_PASSWORD=dockerpass
XDEBUG_CONFIG=
XDEBUG_ENABLE=true
XHPROF_ENABLE=true

Next, run the following command to add your user ID and group ID to your .env file:

echo "MW_DOCKER_UID=$(id -u)
MW_DOCKER_GID=$(id -g)" >> .env

Linux users: If you'd like to use Xdebug features inside your IDE, then create a docker-compose.override.yml file as well:

version: '3.7'
services:
  mediawiki:
    # For Linux: This extra_hosts section enables Xdebug-IDE communication:
    extra_hosts:
      - "host.docker.internal:host-gateway"

4. Create the environment

• Start the containers:

  docker-compose up -d

  The "up" command makes sure that the PHP and webserver containers are running (and any others in the docker-compose.yml file). It is safe to run at any time, and will do nothing if the containers are already running.

  The first time, it may take a few minutes to download new Docker images.

  The -d argument stands for "detached" mode, which run the services in the background. If you suspect a problem with one of the services, you can run it without -d to follow the server logs directly from your termimnal. You don't have to stop the services first, if you ran it with -d and then without, you'll get connected to the already running containers including a decent backscroll of server logs.

  Note that MediaWiki debug logs go to /cache/*.log files (not sent to docker).

• Install PHP dependencies from Composer:

  docker-compose exec mediawiki composer update

• Install MediaWiki:

  docker-compose exec mediawiki /bin/bash /docker/install.sh

Done! The wiki should now be available for you at http://localhost:8080.

Usage

Running commands

You can use docker-compose exec mediawiki bash to open a bash shell in the MediaWiki container. You can then run one or more commands as needed and stay within the container shell.

You can also run a single command in the container directly from your host shell, for example: docker-compose exec mediawiki php maintenance/update.php.

PHPUnit

Run a single PHPUnit file or directory:

docker-compose exec mediawiki bash
instance:/w$ cd tests/phpunit
instance:/w/tests/phpunit$ php phpunit.php path/to/my/test/

See PHPUnit on mediawiki.org for more examples.

Selenium

You can use Fresh to run Selenium in a dedicated container. Example usage:

fresh-node -env -net
npm ci
npm run selenium-test

API Testing

You can use Fresh to run API tests in a dedicated container. Example usage:

export MW_SERVER=http://localhost:8080/
export MW_SCRIPT_PATH=/w
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

Modify the development environment

You can override the default services from a docker-compose.override.yml file, and make use of those overrides by changing LocalSettings.php.

Example overrides and configurations can be found under MediaWiki-Docker on mediawiki.org.

After updating docker-compose.override.yml, run docker-compose down followed by docker-compose up -d for changes to take effect.

Install extra packages

If you need root on the container to install system packages with apt-get for troubleshooting, you can open a shell as root with docker-compose exec --user root mediawiki bash.

Install extensions and skins

To install an extension or skin, follow the intructions of the mediawiki.org page for the extension or skin in question, and look for any dependencies or additional steps that may be needed.

For most extensions, only two steps are needed: download the code to the right directory, and then enable the component from LocalSettings.php.

To install the Vector skin:

1. Clone the skin:

   cd skins/
   git clone https://gerrit.wikimedia.org/r/mediawiki/skins/Vector

2. Enable the skin, by adding the following to LocalSettings.php:

   wfLoadSkin( 'Vector' );

To install the EventLogging extension:

1. Clone the extension repository:

   cd extensions/
   git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/EventLogging

   Alternatively, if you need to extension repositories elsewhere on disk, mount each one as a overlapping volume in docker-compose.override.yml. The is comparable to a symlink, but those are not well-supported in Docker.

   version: '3.7'
   services:
     mediawiki:
       volumes:
         - ~/Code/Vector:/var/www/html/w/skins/vector:cached

2. Enable the extension, by adding the following to LocalSettings.php:

   wfLoadExtension( 'EventLogging' );

Xdebug

By default, you will need to set XDEBUG_TRIGGER=1 in the GET/POST, or as an environment variable, to turn on Xdebug for a request.

You can also install a browser extension for controlling whether Xdebug is active. See the official Xdebug Step Debugging, particularly the "Activating Step Debugging" section, for more details.

If you wish to run Xdebug on every request, you can set start_with_request=yes in XDEBUG_CONFIG in your .env file:

XDEBUG_CONFIG=start_with_request=yes

You can pass any of Xdebug's configuration values in this variable. For example:

XDEBUG_CONFIG=client_host=192.168.42.34 client_port=9000 log=/tmp/xdebug.log

This shouldn't be necessary for basic use cases, but see the Xdebug settings documentation for available settings.

Stop or recreate environment

Stop the environment, perhaps to reduce load when working on something else. This preserves the containers, to be restarted later quickly with the docker-compose up -d command.

docker-compose stop

Destroy and re-create the environment. This will delete the containers, including any logs, caches, and other modifications you may have made via the shell.

docker-compose down
docker-compose up -d

Re-install the database

To empty the wiki database and re-install it:

• Remove or rename the LocalSettings.php file.
• Delete the cache/sqlite directory.
• Re-run the "Install MediaWiki database" command.

You can now restore or copy over any modifications you had in your previous LocalSettings.php file. And if you have additonal extensions installed that required a database table, then also run: docker-compose exec mediawiki php maintenance/update.php.

Troubleshooting

Caching

If you suspect a change is not applying due to caching, start by hard refreshing the browser.

If that doesn't work, you can narrow it down by disabling various server-side caching layers in LocalSettings.php, as follows:

$wgMainCacheType = CACHE_NONE;
$wgMessageCacheType = CACHE_NONE;
$wgParserCacheType = CACHE_NONE;
$wgResourceLoaderMaxage = [
  'versioned' => 0,
  'unversioned' => 0
];

The default settings of MediaWiki are such that caching is smart and changes propagate immediately. Using the above settings may slow down your wiki significantly. Especially on macOS and Windows, where Docker Desktop uses a VM internally and thus has longer file access times.

See Manual:Caching on mediawiki.org for more information.

Xdebug ports

Older versions of Xdebug used port 9000, which could conflict with php-fpm running on the host. This document used to recommend a workaround of telling your IDE to listen on a different port (e.g. 9009) and setting XDEBUG_CONFIG=remote_port=9009 in your .env.

Xdebug 3.x now uses the client_port value, which defaults to 9003. This should no longer conflict with local php-fpm installations, but you may need to change the settings in your IDE or debugger.

Linux desktop, host not found

The image uses host.docker.internal as the client_host value which should allow Xdebug work for Docker for Mac/Windows.

On Linux, you need to create a docker-compose.override.yml file with the following contents:

version: '3.7'
services:
  mediawiki:
    extra_hosts:
      - "host.docker.internal:host-gateway"

With the latest version of Docker on Linux hosts, this should work transparently as long as you're using the recommended docker-compose.override.yml. If it doesn't, first check docker version to make sure you're running Docker 20.10.2 or above, and docker-compose version to make sure it's 1.27.4 or above.

If Xdebug still doesn't work, try specifying 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 in .env, 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

"(Permission Denied)" errors on running docker-compose

See if you're able to run any docker commands to start with. Try running docker container ls, which should also throw a permission error. If not, go through the following steps to get access to the socket that the docker client uses to talk to the daemon.

sudo usermod -aG docker $USER

And then relogin (or newgrp docker) to re-login with the new group membership.

"(Cannot access the database: Unknown error (localhost))"

The environment's working directory has recently changed to /var/www/html/w. Reconfigure this in your LocalSettings.php by ensuring that the following values are set correctly:

$wgScriptPath = '/w';
$wgSQLiteDataDir = "/var/www/html/w/cache/sqlite";