Contributing

This guide covers the release workflow for the Canasta project, how the various repositories work together, and how to create your own Canasta-based distribution.

Repository overview

The Canasta project spans several repositories:

Repository	Description
CanastaBase	Base Docker image with MediaWiki, Apache, PHP, bundled extensions/skins, and maintenance scripts
Canasta	Thin layer on top of CanastaBase that adds additional extensions/skins, patches, and extension-specific maintenance scripts
Canasta-CLI	Go CLI tool for managing Canasta installations

The Docker image hierarchy is:

CanastaBase (mediawiki + core extensions + skins + maintenance scripts)
  └── Canasta (additional extensions/skins, patches, extension-specific maintenance)

Caddy, Varnish, MariaDB, and Elasticsearch/OpenSearch run as separate containers alongside the Canasta web container — they are not part of the Canasta image.

Forking Canasta

There are various reasons you might want to fork Canasta to create your own Canasta-like MediaWiki distribution image. The most common reason is to change the default set of extensions and skins. If you find bugs or want to add generally useful features, please contribute patches to the main repositories instead.

Since version 3.0, Canasta separates generic MediaWiki-handling code (in CanastaBase) from extension- and skin-specific code (in Canasta, which uses CanastaBase as its base image). CanastaBase provides directories for child images to add functionality: config/ for additional MediaWiki settings and maintenance-scripts/ for scripts that run on update. This design gives child images considerable freedom without requiring a fork of CanastaBase itself.

CLI compatibility: The CLI relies on specific behavior in CanastaBase's scripts (maintenance routines, environment variable handling, etc.). If you want your custom image to work with the CLI, you must preserve that contract. To use a custom image with an existing CLI installation, set CANASTA_IMAGE in the installation's .env file to point to your image.

Changing the set of extensions and skins

To offer a different set of extensions and skins, you may only need to modify one file: contents.yaml, which lists the extensions and skins to install in a minimal format. The full syntax is defined in the Recommended Revisions documentation.

The inherits keyword makes it easy to base your set on another listing. You can use the Canasta contents.yaml as a starting point, adding entries for extensions and skins to include or using the remove keyword to exclude them.

Canasta includes special maintenance scripts for Semantic MediaWiki and CirrusSearch. If your distribution does not include one or both of these, you should remove the corresponding scripts. If you add extensions that require similar special handling, you can use these scripts as a model.

Modifying image internals

When making deeper changes to a Canasta-based image:

Never modify _sources/canasta/LocalSettings.php in CanastaBase — this is reserved for fundamental changes needed to keep MediaWiki working on the Canasta stack.
Prefer adding files to the settings/ directory in your image rather than modifying CanastaDefaultSettings.php. It is permissible to change CanastaDefaultSettings.php, but be aware that upstream updates to CanastaBase may also change it, so you will need to reconcile any differences when updating your base image.
Both LocalSettings.php and CanastaDefaultSettings.php live in the CanastaBase repository, not in Canasta.

Release workflow

A typical Canasta release involves changes across one or more repositories. The general flow is:

1. Merge changes into CanastaBase and/or Canasta

Submit and merge pull requests to the relevant repos. For changes that span both CanastaBase and Canasta (e.g., a new MediaWiki version), merge CanastaBase first so the new base image is available when Canasta builds.

2. CI builds on every master push

Every push to master triggers the CI workflow, which:

Builds the Docker image for linux/amd64 and linux/arm64
Pushes the mutable rolling tags: latest, <MW_MAJOR>-latest, <MW_VERSION>-latest, and <MW_VERSION>-<DATE>-<SHA>

3. Bump the VERSION file for a new release

Once all PRs for the release are merged into master, update the VERSION file in the Canasta repository to the new version number (e.g., 3.3.0). This can be done directly on master or via a final PR.

When the CI detects that the VERSION file changed in the push, it also pushes an immutable versioned image tag (e.g., 3.3.0) in the same build. This is the tag that CLI installations are pinned to — it is never overwritten by future builds.

4. Update the CLI default image tag

After the versioned image is published, update the CANASTA_VERSION file in the Canasta-CLI repository to match the new version (e.g., 3.3.0). The build script reads this file and sets DefaultImageTag via ldflags.

This ensures new installations created with canasta create use the new version. Existing installations keep whatever version is in their .env file until explicitly upgraded.

5. Release the CLI

Bump the VERSION file in the Canasta-CLI repository to trigger a new release. The VERSION file controls the CLI version number, which is independent of the Canasta image version in CANASTA_VERSION. You can release new CLI versions without bumping the Canasta image version, and vice versa.

Image tagging strategy

The Canasta Docker image uses several tag types:

Tag	When published	Mutable?	Example
`latest`	Every push to `master`	Yes	`canasta:latest`
`<MW_MAJOR>-latest`	Every push to `master`	Yes	`canasta:1.43-latest`
`<MW_VERSION>-latest`	Every push to `master`	Yes	`canasta:1.43.1-latest`
`<MW_VERSION>-<DATE>-<SHA>`	Every push to `master`	No	`canasta:1.43.1-20260224-abc1234`
`<CANASTA_VERSION>`	Git tag push (auto or manual)	No	`canasta:3.2.0`
`<MW_VERSION>-<DATE>-<PR>`	Pull requests	No	`canasta:1.43.1-20260224-42`

The CLI pins installations to the immutable <CANASTA_VERSION> tag (e.g., 3.2.0). This guarantees reproducible deployments — the image an installation uses does not change unless the user explicitly upgrades.

Updating the CLI default image

The default image tag is controlled by the CANASTA_VERSION file at the repository root. The build script reads this file and injects the value into DefaultImageTag via ldflags.

When canasta create runs, it writes CANASTA_IMAGE=ghcr.io/canastawiki/canasta:<DefaultImageTag> to the installation's .env file. The docker-compose.yml and Kubernetes web.yaml templates reference ${CANASTA_IMAGE:-ghcr.io/canastawiki/canasta:latest} — the latest fallback is never used in practice since CANASTA_IMAGE is always set.

To update:

Change CANASTA_VERSION to the new image version
Submit a PR to Canasta-CLI
After merging, bump VERSION if you want a new CLI release

Version files

The CLI uses two version files:

File	Controls	Example
`VERSION`	CLI version number (triggers release when changed)	`3.6.0`
`CANASTA_VERSION`	Default Canasta Docker image tag	`3.5.1`

These are independent — you can release CLI updates (bug fixes, new commands) without bumping the Canasta image version, and update the pinned Canasta version without changing the CLI version.

Testing changes locally

To test changes to CanastaBase or Canasta before they are published, use --build-from:

# Directory structure expected by --build-from:
# ~/canasta-repos/
#   ├── Canasta/       (required)
#   └── CanastaBase/   (optional — if present, built first)

canasta create -i test-instance -w mywiki -n localhost \
  --build-from ~/canasta-repos

This builds the image(s) locally and uses them for the installation. See Custom Canasta images and Development mode for details.

Help:Contributing

Contents