Help:Upgrading

Upgrading

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

---

How upgrading works

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

1. Updates the CLI itself to the latest version
2. For each installation: pulls the latest Canasta Docker image (or rebuilds it if the installation 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

canasta upgrade

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

canasta upgrade --dry-run

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

Pre-upgrade checklist

1. Back up your data before every upgrade:

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

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 ..., you should:

1. Add your user to the docker and www-data groups:

   sudo usermod -aG docker,www-data $USER

1. Log out and log back in for the group changes to take effect.
2. Stop using sudo with Canasta CLI commands.

See the installation guide for full details on Linux group requirements.

Migrating from a legacy installation

If you have an existing MediaWiki installation 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 installation.

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 installation with the database dump

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

The -d flag imports the SQL dump during installation. 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 installation'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 installation'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 installation:

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 installation's .env file at the root of the installation directory.

8. Restart and verify

Restart the installation and verify that everything is working:

canasta restart -i myinstance

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