Upgrading

This guide covers upgrading Canasta CLI installations and instances. There are three paths depending on what you have today:

• Routine upgrade — you are already on Canasta CLI 4.0.0 or later (Ansible-based) and want the current version.
• Upgrading from Canasta-CLI 3.x (Go) — you have an older Go-based canasta binary installed via install.sh or make install.
• Migrating from a legacy non-CLI instance — you have a MediaWiki install that was set up manually (Docker Compose, bare metal, etc.) without the Canasta CLI.

Routine upgrade

To upgrade an existing Canasta CLI 4.0.0+ install, run:

canasta upgrade

This is a single-step upgrade — canasta upgrade pulls the latest playbooks (native mode) or the latest Canasta CLI Docker image (Docker mode) before upgrading any instances, so you do not need to re-run get-canasta.sh separately.

The canasta upgrade command:

1. Pulls the latest playbooks (native install) or Canasta CLI Docker image (Docker install) — the CLI updates itself first.
2. Refreshes each instance's configuration files from the current Canasta CLI version.
3. Pulls the latest Canasta Docker image (or rebuilds it if the instance was created with --build-from).
4. Runs maintenance/update.php automatically to apply database schema changes.
5. Restarts the containers with the new image.

This upgrades the entire Canasta stack, including the CanastaBase and Canasta Docker images which contain MediaWiki, bundled extensions, and skins. When new Long Term Support (LTS) versions of MediaWiki are released, the upgrade is performed by upgrading to a new CanastaBase image.

Use --dry-run to preview what would change without applying:

canasta upgrade --dry-run

If an instance fails to upgrade, the error is printed and the remaining instances are still upgraded. A summary at the end reports how many succeeded.

Informational files in the instance directory (READMEs, docker-compose.override.yml.example) are created during canasta create but are not recreated during upgrade if you have deleted them. CLI-managed files (such as default.vcl) are always kept up to date.

Pre-upgrade checklist

1. Back up your data before every upgrade:

   canasta backup create -t "pre-upgrade-$(date +%Y%m%d)"

1. Review the Canasta release notes for any breaking changes.
2. Ensure your user has the required group memberships (see Installation — Linux).

Upgrading from Canasta-CLI 3.x (Go)

Canasta-CLI 3.x is the Go-based CLI installed via curl ... install.sh | sudo bash or make install from the Canasta-Go repository (formerly Canasta-CLI). Canasta CLI 4.0.0+ is a python/Ansible reimplementation; see Help:Installation for details.

The upgrade is a two-step process. Both steps preserve your registered instances and their data — the Canasta CLI 4.x reads the same conf.json registry format.

Step 1: Run canasta upgrade to install the bridge

canasta upgrade

This self-updates your existing Canasta-CLI Go binary to the final 3.7.0 "bridge" release. The bridge does not perform any instance upgrades; its only job is to direct you to install the new Canasta CLI.

Step 2: Run the bridge to see migration instructions

After the self-update completes, run any canasta command (for example canasta version). The bridge prints a short message instructing you to run the new installer:

# Docker mode (default — only Docker required on the host):
curl -fsSL https://get.canasta.wiki | bash

# Native mode (requires Python 3.10+ and git):
curl -fsSL https://get.canasta.wiki | bash -s -- --native

See Help:Installation#Install for the difference between Docker and native modes.

Step 3: Verify

canasta version

Output should report Canasta CLI 4.0.0 or later. Your existing instances should appear in canasta list exactly as before.

To then upgrade the instances themselves to the latest Canasta image, run:

canasta upgrade

ℹ️ Note: The canasta upgrade command on the bridge does not upgrade your instances — it only points you to the install script. Instance upgrades happen after you install the new CLI and run canasta upgrade again from the new binary.

Special case: very old Go binaries (pre-3.x)

If your Canasta-CLI binary is so old that it predates the v1.48.0 transition to non-sudo file ownership, your instance's files may be owned by root, which will cause permission errors under the current CLI. Rather than attempting to fix ownership in place, follow the legacy migration flow below: export your database, create a fresh instance with the new CLI, and copy in your settings and uploads.

Migrating from a legacy non-CLI instance

If you have an existing MediaWiki instance that was not created with the Canasta CLI (for example, a manual Docker Compose setup or a bare-metal install), you can migrate it to a CLI-managed Canasta instance.

1. Export your database

Use mariadb-dump (or the equivalent for your database engine) to create a SQL dump of your wiki database:

mariadb-dump -u root -p wikidb > wikidb.sql

2. Create a new Canasta instance with the database dump

canasta create -i myinstance -w mywiki -n example.com -d wikidb.sql

The -d flag imports the SQL dump during instance creation. The admin account will be created only if it does not already exist in the imported database.

3. Copy your settings files

Copy your existing PHP settings files (e.g., LocalSettings.php customizations) into the new instance's global settings directory:

cp MySettings.php /path/to/myinstance/config/settings/global/

If you are running a wiki farm, place per-wiki settings in config/settings/wikis/<wikiid>/.

4. Copy uploaded images

Copy your uploaded files into the instance's images/<wiki-id>/ directory:

cp -r /old/wiki/images/* /path/to/myinstance/images/<wiki-id>/

5. Copy Caddyfile customizations

If you had custom web server rules, copy them to the Canasta Caddyfile locations:

• config/Caddyfile.site — per-site directives (headers, redirects, etc.)
• config/Caddyfile.global — global Caddy options

Do not edit config/Caddyfile directly, as it is regenerated when wikis change.

6. Copy custom extensions and skins

If you have extensions or skins that are not bundled with Canasta, copy them into the instance:

cp -r /old/wiki/extensions/MyExtension /path/to/myinstance/extensions/
cp -r /old/wiki/skins/MySkin /path/to/myinstance/skins/

7. Carry over .env settings

Review your old configuration and carry over any custom environment variables (database credentials, MW_SITE_SERVER, etc.) into the new instance's .env file at the root of the instance directory.

8. Restart and verify

Restart the instance and verify that everything is working:

canasta restart

The update.php maintenance script runs automatically on container startup, so database schema migrations will be applied.