MediaWiki-Docker/Configuration recipes/Wiki farm

The setup below does not include configuring the jobrunner service to run jobs on all wikis. You would have to edit the entry point to achieve that.

Sometimes you may need to test changes on a multi-wiki environment. By following the steps below, you will set up a two-wiki wiki farm using MediaWiki-Docker.

The steps below assume that your main wiki's database is called my_wiki, and that you access it using wiki (short URLs), and w (long URLs), which are the default values in MediaWiki-Docker. We will create a new wiki called secondwiki that you can access using secondwiki (short) or w2 (long).

Docker configuration

• Begin by creating a docker-compose.override.yml file. We will use this to add a volume for the new wiki, and to update the Apache configuration by using a custom dockerfile. The end result should look something like the following:

  services:
    mediawiki:
      # On Linux, these lines ensure file ownership is set to your host user/group
      user: "${MW_DOCKER_UID}:${MW_DOCKER_GID}"
      volumes:
        - ./:/var/www/html/w2:cached
    mediawiki-web:
      user: "${MW_DOCKER_UID}:${MW_DOCKER_GID}"
      volumes:
        - ./:/var/www/html/w2:cached
      build:
        context: ./path/to/custom/Dockerfile/Directory
        dockerfile: Dockerfile
    mediawiki-jobrunner:
      volumes:
        - ./:/var/www/html/w2:cached
  

• Create the custom dockerfile in the directory specified above. We will use this to update the Apache configuration for short URLs:

  # Important: Make sure the version here matches the latest version of the mediawiki-web image in docker-compose.yml
  FROM docker-registry.wikimedia.org/dev/bookworm-apache2:1.0.0
  
  RUN grep -q "secondwiki" /etc/apache2/sites-available/000-default.conf || sed -i '/RewriteEngine On/a RewriteRule ^/?secondwiki(/.*)?$ %{DOCUMENT_ROOT}/w2/index.php' /etc/apache2/sites-available/000-default.conf
  

• Make sure that the containers aren't running (docker compose down), then run docker compose build && docker compose up -d in the MediaWiki root directory.
• If everything went fine, your wiki should now be accessible using either the old wiki and w URLs as well as the new secondwiki and w2 ones. Take a moment to verify that.

MediaWiki configuration

For this section, we are going to add a few settings to LocalSettings.php as described in the guide for creating a wiki farm. The code snippet below should work out of the box; refer to the inline comments for explanations.

// This maps URL paths to DB names. Note that we need to include both long and short URLs
$wikis = [
   'wiki' => 'my_wiki',
   'w' => 'my_wiki',
   'secondwiki' => 'secondwiki',
   'w2' => 'secondwiki',
];
if ( defined( 'MW_DB' ) ) {
   // Automatically set from --wiki option to maintenance scripts.
   $wikiID = MW_DB;
} else {
   $path = explode( '/', $_SERVER['REQUEST_URI'] ?? '', 3 )[1] ?? '';
   // Note that we are falling back to the main wiki for convenience. You could also throw an exception instead.
   $wikiID = $_SERVER['MW_DB'] ?? $wikis[ $path ] ?? 'my_wiki';
}

/** @var SiteConfiguration $wgConf */
$wgLocalDatabases = $wgConf->wikis = array_values( array_unique( $wikis ) );
$wgConf->suffixes = [ 'wiki' ];
$wgDBname = $wikiID;

// These are the only settings you will have to include here. Everything else is optional.
$wgConf->settings = [
   'wgCanonicalServer' => [
      'default' => 'http://localhost:8080'
   ],
   'wgArticlePath' => [
      'my_wiki' => '/wiki/$1',
      'secondwiki' => '/secondwiki/$1',
   ],
   'wgScriptPath' => [
      'my_wiki' => '/w',
      'secondwiki' => '/w2',
   ],
   'wgSitename' => [
      'my_wiki' => 'MainWiki',
      'secondwiki' => 'SecondWiki',
   ],
];
$wgConfGlobals = $wgConf->getAll( $wgDBname  );
extract( $wgConfGlobals );

Make sure to put the above after the lines which includes the PlatformSettings.php file, as that will otherwise override the $wgArticlePath setting.

Also, for each setting that is now defined above (everything inside $wgConf->settings plus $wgDBname), comment out any pre-existing definition elsewhere in LocalSettings.php.

At this point, if you access your main wiki it should work as usual, whereas if you try to access the new wiki it should throw a database error. This is normal, because we haven't created our database yet. One way to do that is to temporarily move your LocalSettings out of the way (i.e., rename it to something else), then open a shell inside the mediawiki container (docker compose exec mediawiki bash) and run the following:

php maintenance/install.php \
  --server "$MW_SERVER" \
  --scriptpath="$MW_SCRIPT_PATH" \
  --dbtype "$MW_DBTYPE" \
  --dbpath "$MW_DBPATH" \
  --dbname "secondwiki" \
  --lang "$MW_LANG" \
  --pass "$MW_PASS" \
  "$MW_SITENAME" "$MW_USER"

You can then delete the newly-generated LocalSettings.php file and restore the old one. Finally, run the updater for the new wiki: php maintenance/update.php --quick --wiki secondwiki.

Everything should be up and running at this point!