Extensions and skins¶

Contents¶

Overview
Bundled vs. user extensions
Listing available extensions and skins
Enabling extensions and skins
Global vs. per-wiki
Enabling multiple at once
Disabling extensions and skins
Adding extensions not bundled with Canasta
Overriding a bundled extension
Composer dependencies
Semantic MediaWiki
CirrusSearch / Elasticsearch
How it works under the hood
Important notes

Overview¶

Canasta bundles over 100 extensions and skins. The CLI provides commands to enable and disable them without manually editing PHP files:

canasta extension list — list available extensions
canasta extension enable — enable one or more extensions
canasta extension disable — disable one or more extensions
canasta skin list — list available skins
canasta skin enable — enable one or more skins
canasta skin disable — disable one or more skins

See the CLI Reference for the full list of flags and usage.

Bundled vs. user extensions¶

Canasta distinguishes between two types of extensions and skins:

Bundled extensions/skins are included in the Canasta Docker image. Inside the container, they live in canasta-extensions/ and canasta-skins/. These are the extensions listed by canasta extension list and canasta skin list, and are what the enable/disable commands manage.

User extensions/skins are extensions you add yourself. On the host, they go in the extensions/ and skins/ directories of your installation. These are not managed by the CLI — you load them by adding wfLoadExtension() or wfLoadSkin() calls in a settings file under config/settings/.

Listing available extensions and skins¶

To see what bundled extensions are available:

canasta extension list -i myinstance

To see available skins:

canasta skin list -i myinstance

These commands list the names of all bundled extensions or skins shipped with the Canasta image. The installation must be running.

Enabling extensions and skins¶

canasta extension enable VisualEditor -i myinstance
canasta skin enable Vector -i myinstance

Global vs. per-wiki¶

By default, enabling an extension applies to all wikis in the installation. To enable an extension for a specific wiki only, use the -w flag:

# Enable for all wikis
canasta extension enable VisualEditor -i myinstance

# Enable for a specific wiki
canasta extension enable SemanticMediaWiki -i myinstance -w docs

Disabling works the same way — without -w it affects the global setting, with -w it affects that wiki only.

Enabling multiple at once¶

Pass a comma-separated list of names:

canasta extension enable VisualEditor,Cite,Scribunto -i myinstance
canasta skin enable Vector,CologneBlue -i myinstance

Each extension is processed independently. If one name is invalid, the others are still enabled.

Disabling extensions and skins¶

canasta extension disable VisualEditor -i myinstance
canasta skin disable CologneBlue -i myinstance -w docs

The CLI can only disable extensions that were enabled using the CLI. If you manually created a settings file to load an extension, the CLI will not remove it.

Adding extensions not bundled with Canasta¶

To use an extension that is not included in the Canasta image:

Place the extension in the extensions/ directory of your installation (or skins/ for skins)
Create a PHP settings file to load it — either in config/settings/global/ (for all wikis) or config/settings/wikis/{wiki-id}/ (for a specific wiki):

<?php
wfLoadExtension( 'MyCustomExtension' );

Restart the installation:

canasta restart -i myinstance

User extensions are not shown by canasta extension list and cannot be managed with enable/disable. They are loaded by the settings files you create.

Overriding a bundled extension¶

If you need a different version of an extension than the one bundled with Canasta, you can override it by placing your version in the extensions/ (or skins/) directory with the same name. This is useful when you need a newer release, a patched fork, or a development branch of a bundled extension.

This works because the host's extensions/ directory is mounted to user-extensions/ inside the container, and user extensions are symlinked into the final extensions/ directory after bundled extensions, so they take precedence.

To override a bundled extension:

Place your version of the extension in extensions/{ExtensionName}/
Restart the installation: canasta restart -i myinstance
The bundled version will be ignored in favor of yours

No changes to settings files are needed — the existing wfLoadExtension() call (whether CLI-managed or manual) will load from your copy automatically.

To revert to the bundled version, remove your copy from extensions/ and restart.

Composer dependencies¶

Canasta uses a unified composer autoloader. At build time, bundled extensions and skins that need composer dependencies are merged into MediaWiki's root vendor/autoload.php via the composer merge plugin. This means extensions like SemanticMediaWiki, Maps, and Bootstrap all share a single autoloader with MediaWiki core.

The file config/composer.local.json controls which composer.json files are merged. The build-time default includes specific entries for bundled extensions that need composer:

{
    "extra": {
        "merge-plugin": {
            "include": [
                "extensions/SemanticMediaWiki/composer.json",
                "extensions/Maps/composer.json",
                "..."
            ]
        }
    }
}

If you add a user-extension that has composer dependencies, add its composer.json to the include list manually:

{
    "extra": {
        "merge-plugin": {
            "include": [
                "extensions/SemanticMediaWiki/composer.json",
                "extensions/Maps/composer.json",
                "...",
                "user-extensions/MyExtension/composer.json"
            ]
        }
    }
}

When the container starts, Canasta detects if config/composer.local.json or any referenced composer.json has changed since the last run, and re-runs composer update if needed.

To opt out of runtime composer updates, delete config/composer.local.json or empty its include array. The build-time autoloader will be used as-is.

Semantic MediaWiki¶

Semantic MediaWiki (SMW) is bundled with Canasta and lets you store and query structured data within your wiki.

Enabling Semantic MediaWiki¶

Add the following to a settings file (e.g., config/settings/global/SemanticMediaWiki.php):
```
<?php
wfLoadExtension( 'SemanticMediaWiki' );
enableSemantics( 'example.org' );
```
Replace example.org with your wiki's domain name.
Restart Canasta:
```
canasta restart -i myinstance
```

On the first startup after enabling SMW, Canasta automatically runs setupStore.php to initialize the SMW database tables. This creates a smw.json configuration file in config/smw/ on the persistent volume, so the setup only runs once.

Rebuilding SMW data¶

After initial setup, you need to run rebuildData.php to populate the SMW store. Canasta does not run this automatically because it can take a long time on large wikis. Use the extension maintenance command:

canasta maintenance extension -i myinstance SemanticMediaWiki rebuildData.php

For large wikis, pass options to run in segments:

canasta maintenance extension -i myinstance SemanticMediaWiki rebuildData.php -s 1000 -e 2000

See Running extension maintenance scripts for more examples.

Notes¶

The enableSemantics() function is provided by SMW's composer autoloader. Canasta's unified autoloader ensures it is available without any additional steps.
SMW's smw.json is stored persistently in config/smw/ so it survives container recreations.
If you need to reinitialize the SMW store (e.g., after a major upgrade), delete config/smw/smw.json and restart Canasta.

CirrusSearch / Elasticsearch¶

CirrusSearch replaces MediaWiki's default search with Elasticsearch. Canasta includes both CirrusSearch and Elasticsearch as built-in services — Elasticsearch runs in a dedicated container alongside the web container.

Enabling CirrusSearch¶

Enable the CirrusSearch and Elastica extensions:

canasta extension enable CirrusSearch,Elastica -i myinstance

No additional configuration is needed. Canasta's built-in Elasticsearch container is already configured as the search backend.

Rebuilding the search index¶

After enabling CirrusSearch (or after a major upgrade), you need to build the search index. This is a three-step process:

Step 1 — Configure index mappings:

canasta maintenance extension -i myinstance CirrusSearch UpdateSearchIndexConfig.php --reindexAndRemoveOk --indexIdentifier now

Step 2 — Index page content:

canasta maintenance extension -i myinstance CirrusSearch ForceSearchIndex.php --skipLinks --indexOnSkip

Step 3 — Index links:

canasta maintenance extension -i myinstance CirrusSearch ForceSearchIndex.php --skipParse

All three steps must run in order. On large wikis, the indexing steps (2 and 3) can take a significant amount of time.

Recreating the index from scratch¶

To destroy and recreate the index (e.g., after changing analyzers or mappings), use --startOver instead of --reindexAndRemoveOk --indexIdentifier now in step 1:

canasta maintenance extension -i myinstance CirrusSearch UpdateSearchIndexConfig.php --startOver

Then run steps 2 and 3 as above.

Wiki farms¶

In a wiki farm, each wiki has its own search index. Use --wiki to target a specific wiki:

canasta maintenance extension -i myinstance --wiki=docs CirrusSearch UpdateSearchIndexConfig.php --reindexAndRemoveOk --indexIdentifier now
canasta maintenance extension -i myinstance --wiki=docs CirrusSearch ForceSearchIndex.php --skipLinks --indexOnSkip
canasta maintenance extension -i myinstance --wiki=docs CirrusSearch ForceSearchIndex.php --skipParse

Or use --all to rebuild indexes for every wiki:

canasta maintenance extension -i myinstance --all CirrusSearch UpdateSearchIndexConfig.php --reindexAndRemoveOk --indexIdentifier now
canasta maintenance extension -i myinstance --all CirrusSearch ForceSearchIndex.php --skipLinks --indexOnSkip
canasta maintenance extension -i myinstance --all CirrusSearch ForceSearchIndex.php --skipParse

See Running extension maintenance scripts for general usage of the extension maintenance command.

How it works under the hood¶

When you run canasta extension enable VisualEditor, the CLI creates a small PHP file that loads the extension:

Global enable creates config/settings/VisualEditor.php containing:

<?php
// This file was generated by Canasta
wfLoadExtension( 'VisualEditor' );

Per-wiki enable (-w docs) creates config/docs/VisualEditor.php with the same content.

These files are loaded by MediaWiki alongside the files in config/settings/global/ and config/settings/wikis/{wiki-id}/.

Disabling deletes that file. The CLI checks for the // This file was generated by Canasta comment before deleting, so it will not remove files you created manually.

Since these files are in the mounted config/ volume, they persist across container restarts.

Important notes¶

Extension and skin names are case-sensitive. Use the exact name as shown by canasta extension list or canasta skin list.
The installation must be running. The commands execute inside the web container, so containers must be up.
Enabling is idempotent. Running enable on an already-enabled extension is a no-op.
Disable only works on CLI-managed extensions. Manually created settings files are left alone.
No restart required. Changes take effect on the next page load since PHP reads the settings files on each request.