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 the current Ansible-based Canasta CLI and want the latest release.
• Upgrading from a legacy Go-based CLI — 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 install, run:

canasta upgrade

This is a single-step upgrade — canasta upgrade updates the CLI itself first and then upgrades your instances, so you do not need to re-run get-canasta.sh separately. By default it moves the CLI to the latest released version: native mode checks out the latest release tag, and Docker mode pulls the matching released canasta-ansible image. Pass --dev to track development builds (the head of main) instead — see Tracking development builds below.

The canasta upgrade command:

1. Updates the CLI itself first — to the latest released version by default, or the head of main with --dev (native installs check out the release tag; Docker installs pull the matching image).
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.

Template-seeded files in the instance directory — informational files such as READMEs and docker-compose.override.yml.example, and seeded config files such as config/default.vcl and the bundled config/settings/global/*.php — are copied in once when the instance is created and then owned by you. Upgrade is deliberately no-clobber: it never overwrites them, and does not recreate ones you have deleted, so your local edits are safe.

To adopt an improved version that a newer CLI ships, or to restore a seed file you deleted, use canasta config refresh-template:

# List seed files whose instance copy differs from the current template
canasta config refresh-template

# Show the diff for one file (changes nothing)
canasta config refresh-template config/default.vcl

# Overwrite the instance copy with the shipped version (replaces your edits)
canasta config refresh-template config/default.vcl --yes

The command is read-only unless --yes is given: with no arguments it lists the template-seeded files whose instance copy differs from the version shipped in the current CLI; with one or more files it shows the diff but changes nothing. Review the diff first — --yes replaces your local edits to that file. Rendered files (.env, config/wikis.yaml, the Caddyfile) are not refreshed here — regenerate those with canasta config regenerate — and per-wiki Settings.php is yours and is never overwritten.

Tracking development builds

By default canasta upgrade tracks released versions — the most recent vX.Y.Z tag. To follow the latest development build instead, add --dev:

canasta upgrade --dev

This tracks the head of the main branch (the previous default behavior). A later canasta upgrade without --dev returns the CLI to the latest release.

canasta upgrade never moves the CLI backward. If you are running a development build that is already ahead of the latest release tag, a default (release-channel) upgrade keeps your current build rather than checking out the older release, and tells you so; it advances to a release only once a newer one is tagged.

To go the other way — return to the latest supported release from a development build, for instance to step back before a newer release has been tagged — re-run the installer. Unlike canasta upgrade, get-canasta.sh always sets the CLI to the latest release rather than only moving forward, so it can move you back onto the release. Run it for the mode you installed with — Docker mode is the default, so add --native for a native install (otherwise you would switch from native to Docker):

# Docker install
curl -fsSL https://get.canasta.wiki | bash

# Native install
curl -fsSL https://get.canasta.wiki | bash -s -- --native

(Add --dev to keep tracking development builds instead.)

When running a development build, canasta version reports dev in place of a version number, because the reported version may not match the eventual release. Released installs continue to report their vX.Y.Z version.

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 a legacy Go-based CLI

If you have an older Go-based canasta binary (installed via curl ... install.sh | sudo bash or make install from the Canasta-Go repository), follow this two-step migration. Both steps preserve your registered instances and their data — the current Canasta CLI reads the same conf.json registry format. See Help:Installation for details on the current Ansible-based CLI.

Step 1: Run canasta upgrade from your existing binary

canasta upgrade

This self-updates the Go binary to its final release, which is purpose-built to redirect you to the new installer. It does not perform any instance upgrades.

Step 2: Run any canasta command to see migration instructions

After the self-update completes, run any canasta command (for example canasta version). It 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 the current Ansible-based Canasta CLI. 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 old Go binary does not upgrade your instances — it only points you to the install script. Instance upgrades happen after you install the current CLI and run canasta upgrade again from it.

Special case: instance files owned by root

If your Canasta-CLI binary is old enough that your instance's files are owned by root, you will see 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 current 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.