Canasta: Documentation

Overview

Canasta is, at heart, a MediaWiki Docker image. There are other Docker images available for MediaWiki, but one big strength of Canasta is that it bundles in a variety of related software, including 9 skins and 139 extensions. Below are the list of skins and extensions that come included. By default, only the Vector skin, out of all of these skins and extensions, is actually "installed"; in order to install any of the rest in your container, you just have to add a call to wfLoadSkin() or wfLoadExtension() for it to your LocalSettings.php file.

There are (theoretically) dozens of skins, and over 1,000 extensions, available for MediaWiki. So how was the set of skins and extensions in Canasta decided on? First, all of the skins and extensions that are bundled in with the official distribution of MediaWiki (3 skins and 28 extensions in all) are included in Canasta; see here for the full list.

Beyond this group, the general criteria are that they must work well with Canasta's MediaWiki version (1.35); they must be well-maintained, and be likely to remain well-maintained in the future; and they must provide important functionality that no other extension or skin that's included does.

Administrators who want to add some skin or extension that is not in this list to their wiki can easily do so in the standard way: by downloading it, adding it to either the /skins or /extensions directory, and adding the relevant call to either wfLoadSkin() or wfLoadExtension() to LocalSettings.php.

Canasta cannot yet be run on computers that use ARM processors, which means that it cannot yet be used on most Apple computers.

Extensions included in Canasta

Analytics

Contribution Scores · Editcount · GoogleAnalyticsMetrics · GTag · RottenLinks · WhoIsWatching

Automated page creation & modification

Data Transfer · Page Exchange · Replace Text

HTML & multimedia support

EmbedVideo · Flex Diagrams · Graph · HTML Tags · Maps · Math · SimpleMathJax · Widgets

Meta tags

Description2 · OpenGraphMeta · WikiSEO

PDF export

Collection

Approved Revs · LockAuthor · Lockdown

Social tools

AJAXPoll · SocialProfile · VoteNY

Spam control

AbuseFilter · ConfirmEdit · Nuke · SmiteSpam · SpamBlacklist · TitleBlacklist

Translation

LocalisationUpdate · UniversalLanguageSelector

User management

CheckUser · LookupUser · Renameuser · UserMerge

Contents

The overall contents of Canasta are as follows:

• Debian Linux v. 11 ("Bullseye")
• Apache HTTP Server v. 2.4.38
• MySQL (via its own Docker image)
• PHP v. 7.4
• MediaWiki v. 1.35.6, in addition to many skins and extensions (see above)
• Elasticsearch 6.8.20
• A sitemap auto-generation script, which stores the sitemap to the directory /var/www/mediawiki/w/sitemap
• A variety of other utilities: ffmpeg, Git, ImageMagick, iputils-ping, Vim, etc.
• A number of PHP and JSON files and directories (see below)

Being a Docker image, Canasta places some files and directories in the host operating system as bind mounts - files and directories associated with the image but which are not contained in the Docker image's container itself, and which the administrator can thus modify, because they will not be removed or overwritten if the Docker image is updated. Canasta also stores the database outside of the Docker image, although this is stored as a volume (named "mysql-data-volume") and not a bind mount.

In Canasta, there are six bind mounts, which appear in the host OS as the files LocalSettings.php and composer.local.json, and the directories images/, extensions/, settings/ and skins/. Besides the database itself, these are the only six files or directories that administrators should modify.

An explanation of the relevant parts of the Canasta image:

• LocalSettings.php - The standard main settings file of MediaWiki. In Canasta it is hidden from administrators, and very short: it simply includes two other files, CanastaDefaultSettings.php and CanastaUtils.php.
• CanastaDefaultSettings.php - Holds a set of Canasta-specific default settings for MediaWiki variables like \$wgScriptPath.
• CustomSettings.php - By default, holds the settings, and extension and skin inclusions, that administrators want for this wiki. It appears to administrators as a file called LocalSettings.php.
• CanastaUtils.php - A short file that defines the (now-deprecated) Canasta-specific utility functions cfLoadExtension() and cfLoadSkin() - this file may go away at some point.
• composer.canasta.json - A Canasta-specific Composer file, meant for installing skins and extensions that require additional libraries.
• composer.local.json - A wiki-specific Composer file, for installing the dependencies of additional skins and extensions (it cannot be used to directly download skins and extensions, only their dependencies).
• canasta-extensions/ - A directory that holds all of Canasta's 100+ bundled extensions.
• canasta-skins/ - A directory that holds all of Canasta's 9 bundled skins.
• user-extensions/ - A directory that holds any locally-installed extensions.
• user-skins/ - A directory that holds any locally-installed skins.
• images/ - Simply MediaWiki's standard images/ directory. This the one part of core MediaWiki that is directly exposed to administrators.
• settings/ - A directory that can optionally hold any additional PHP settings files that admins want to provide. Any such files are called after LocalSettings.php, in alphabetical order.
• extensions/ - A directory that holds automatically-generated symlinks to extensions in both the canasta-extensions/ and user-extensions/ directories.
• skins/ - A directory that holds automatically-generated symlinks to skins in both the canasta-skins/ and user-skins/ directories.

Running maintenance scripts

Usually, you don't need to run maintenance scripts. update.php is always ran during the container startup process, so if you need to run it, it's best to remove the existing container and spin up a new one. The job queue is always automatically ran during the entire life of the container.

However, in the case you do need to run them, you can use:

sudo docker-compose exec web php /var/www/mediawiki/w/maintenance/SCRIPT_NAME.php

Creating Canasta-based distributions

Besides being usable as a downloadable itself, Canasta can also be used as the basis for for other MediaWiki distributions – letting you customize the exact set of skins and extensions available while keeping all the useful functionality contained within Canasta. You can also use Canasta as the basis for a Docker image for a single wiki – enabling easy, reliable deployment of a code set.

1. Clone the Canasta image's repo into your Canasta stack repo by doing, in the base directory of your stack repo, this command: git clone https://github.com/CanastaWiki/Canasta
2. Edit the docker-compose.override.yml file. Under the web container's configuration, add:
image: canasta:dev
build:
context: ./Canasta/

This will use the Dockerfile located in the newly-added Canasta/ directory.

If you made no other changes to your docker-compose.override.yml file, it should appear to be:

version: '3.7'
services:
web:
image: canasta:dev
build:
context: ./Canasta/

Making a derivative image

Canasta supports creating derivative images using your own Dockerfile when done in the officially supported way.

Rather than forking the Canasta image's repo and modifying its Dockerfile, the correct way to make a derivative image is by creating your own Dockerfile whose base image is the Canasta image. The directives on your Dockerfile therefore is quite concise, clean, and only contain changes made to Canasta.

You can change _sources/canasta/CanastaDefaultSettings.php however you want, but you should never change _sources/canasta/LocalSettings.php, as this is reserved for Canasta developers to make fundamental changes needed to keep MediaWiki working on the Canasta tech stack.

Keep in mind:

• Derivative images are officially supported by Canasta, but only if these requirements are followed.
• CanastaDefaultSettings.php will still be changed by Canasta developers. Whenever you update the base image your derivative is using, it is your responsibility to incorporate new changes to it.

Contributing to Canasta

If you want to contribute changes to base Canasta rather than simply making a change in a derivative image, you can make changes to the Canasta image at https://github.com/CanastaWiki/Canasta.