Upgrading

This guide covers upgrading Canasta instances and migrating from legacy (non-CLI) setups.

How upgrading works

The canasta upgrade command updates the CLI binary and all registered instances:

1. Updates the CLI itself to the latest version
2. For each instance: pulls the latest Canasta Docker image (or rebuilds it if the instance was created with --build-from)
3. Restarts the containers with the new image
4. Runs maintenance/update.php automatically to apply any database schema changes

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, this is also how that upgrade is performed — by upgrading to a new version of CanastaBase that includes the updated MediaWiki version.

canasta upgrade

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.

ℹ️ Note: The CLI version and the Canasta Docker image version are independent. A CLI upgrade may not change the Docker image version, and vice versa. The canasta version command shows both versions.

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 Version notes below if upgrading from an older release).

Version notes

The CLI's relationship with sudo changed over several releases:

Version	Change
v1.48.0	CLI began handling www-data file ownership internally, enabling commands to run without sudo.
v1.65.0	sudo removed from installer messages and documentation examples.
v1.127.0	www-data group requirement formally documented.

Upgrading from pre-v1.48.0

If you previously ran commands with sudo canasta ..., your instance's files will be owned by root, which will cause permission errors under the current CLI. Simply stopping sudo is not enough — the file ownership must be corrected, and different files require different ownership (some must be owned by your user, others by the web server group, which varies by Linux distribution).

Rather than attempting to fix ownership in place, the recommended approach is to export your data and create a fresh CLI-managed instance. Follow the steps in Migrating from a legacy instance below.

Before starting, ensure your user is in the docker and web server groups as described in the Installation guide.

Migrating from a legacy 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. 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.