Meza/Installing additional extensions

Meza comes pre-built with many extensions, but additional extensions can be added to an installation. To do so:

Add the extensions to the MezaLocalExtensions.yml configuration file
Run sudo meza deploy <env> where "env" is your environment name (probably "monolith")

[Pro-Tip] If you are just adding extensions and don't want to go through a "full" deploy, you can run the command:

sudo meza deploy <env> --tags mediawiki --skip-tags mediawiki-core,verify-wiki -vv

This performs just the MediaWiki plays and explicitly excludes the core MediaWiki stuff and its overall verifications. This is helpful when you're just tweaking the MezaLocalExtensions.yml file. The -vv provides a level 2 verbosity in the deploy output which is helpful when you are troublshooting new extensions.

Adding extensions

Extensions can be added to /opt/conf-meza/public/MezaLocalExtensions.yml in the following ways. If adding your first extension, please make sure the part that says list: [] (an empty list) is changed to list:. Then add extensions as follows.

Standard extension configuration

  - name: CommentStreams
    repo: https://gerrit.wikimedia.org/r/mediawiki/extensions/CommentStreams.git
    version: master
    config: |
      $wgCommentStreamsEnableTalk = true;

Legacy extensions

If the extension you're trying to install has documentation on mediawiki.org saying to put a require_once statement into LocalSettings.php, then extension uses the legacy loading method. To add it, include legacy_load: True as follows:

  - name: UserJourney
    repo: https://github.com/darenwelsh/UserJourney
    version: master
    legacy_load: True
    config: |
      $fakeVarJustForTesting = false;

Composer installation

If the extension says to use Composer to install it, use the following format:

  - name: Semantic Breadcrumb Links
    composer: mediawiki/semantic-breadcrumb-links
    version: "~1.3"
    config: |
      $egSBLTryToFindClosestDescendant = true;

Note: composer installation won't automatically add the wfLoadExtension() so if that's needed (e.g. Lingo) then simply specify it in the 'config' section because the config section gets output to Extensions.php.

Limiting to specific wikis

Additionally, MezaLocalExtensions.yml is able to limit the inclusion of extensions to specific wikis as follows. This would limit Extension:CommentStreams to only be loaded by the "robo" and "cronus" wikis.

  - name: CommentStreams
    repo: https://gerrit.wikimedia.org/r/mediawiki/extensions/CommentStreams.git
    version: master
    config: |
      $wgCommentStreamsEnableTalk = true;
    wikis:
      - robo
      - cronus

Extensions that require a separate Composer install step

Some extensions, like Extension:Elastica, say that in addition to downloading the code you must also cd into the Elastica directory and then run composer install. To make Meza handle this for you, add composer_merge: True to your extension configuration:

  - name: Elastica
    repo: https://gerrit.wikimedia.org/r/mediawiki/extensions/Elastica.git
    version: "{{ mediawiki_default_branch }}"
    composer_merge: True

Note: Elastica is installed on Meza by default, so this is for example only.

Extensions that require a Git submodule step

Some extensions, perhaps only Extension:VisualEditor and Extension:Widgets, say that in addition to downloading the code you must also cd into the extension directory then run git submodule update --init. To make Meza handle this for you, add git_submodules: True to the extension's configuration:

  - name: Widgets
    repo: https://gerrit.wikimedia.org/r/mediawiki/extensions/Widgets.git
    version: "{{ mediawiki_default_branch }}"
    git_submodules: True

- name: VisualEditor
  repo: https://gerrit.wikimedia.org/r/mediawiki/extensions/VisualEditor.git
  version: "{{ mediawiki_default_branch }}"
  git_submodules: True

Note: Meza installs Visual Editor for you by default.

Example MezaLocalConfig.yml

---
list:
  # A legacy loaded extension
  - name: UserJourney
    repo: https://github.com/darenwelsh/UserJourney
    version: master
    legacy_load: True
    config: |
      $fakeVarJustForTesting = false;

  # A modern loaded extension, limited just to the demo wiki
  - name: CommentStreams
    repo: https://gerrit.wikimedia.org/r/mediawiki/extensions/CommentStreams.git
    version: master
    config: |
      $wgCommentStreamsEnableTalk = true;
    wikis:
      - demo

  # A Composer loaded extension (these cannot be limited to specific wikis)
  - name: Semantic Breadcrumb Links
    composer: mediawiki/semantic-breadcrumb-links
    version: "~1.3"
    config: |
      $egSBLTryToFindClosestDescendant = true;

Extensions from private repositories

In order to use extensions from private Git repositories, use the public SSH key of user meza-ansible (root in older versions of Meza). In GitLab this key is set as a "deploy key" in the extension's settings. For GitHub private repos, deploy keys can only be used for a single repo, so add meza-ansible's public key to your account, or else GitHub recommends that you setup a separate 'machine account' and invite that account to your project. To get meza-ansible's public key, do:

sudo su meza-ansible
cd ~/.ssh
cat id_rsa.pub

Then copy the output of the last command into GitLab's deploy key; or to your GitHub account at https://github.com/settings/keys

Adding extensions to Meza core

There is a file very similar to MezaLocalExtensions.yml located at config/core/MezaCoreExtensions.yml. This is the list of extensions installed as part of every Meza installation. If you want to request that an extension be added to Meza core you'll need to edit this file in the same way that you edit MezaLocalExtensions.yml, and then submit a pull request to nasa/meza. The only difference in functionality between the core and local files is that MezaCoreExtensions.yml does not support limiting extensions to specific wikis.

Quick Ref for Specific Extensions

Looking for the "meza ready" code for a specific extension that is not in Meza? Feel free to check the following page to see if someone has shared their installation code:

Meza/Extension Installation Community Cheat-Sheet