Upgrading

From Canasta Wiki

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

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 within the current major — it never crosses a major-version boundary on its own: native mode checks out the latest matching release tag, and Docker mode pulls the matching released canasta-ansible image. Pass --allow-major to move to the latest release overall, including a new major version (see Crossing a major version). 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 within the current major by default, to the latest release overall with --allow-major, 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, including regenerating the Caddyfile.
  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. On Kubernetes, the pods are redeployed when the instance's image tag changes. A gitops-managed Kubernetes instance is not redeployed; see below.

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 — including when its restart fails, for example because the web container never becomes healthy — the error is printed and the remaining instances are still upgraded. A summary at the end reports how many succeeded and names each instance that failed and why, and the command exits with an error. When the web container never becomes healthy, the error leads with the cause the container logged, such as an extension whose files are missing, and a hint for fixing it (see Troubleshooting). After fixing the cause, run canasta upgrade again: it restarts each instance whose restart failed and reports it upgraded.

If the web container's startup composer update failed on a restarted instance, the upgrade warns about it; see Composer configuration.

Because the Caddyfile is a rendered file, upgrading is how improvements to it reach existing instances. On Docker Compose, a running instance that the upgrade does not restart has its Caddy reloaded with the regenerated Caddyfile, so the change takes effect without downtime. On Kubernetes, the regenerated Caddyfile is applied when the upgrade restarts the instance (for example because the image tag changed), or otherwise at the next canasta restart.

On Docker Compose, the upgrade also moves every instance on each host behind the HAProxy edge before upgrading it. Each instance keeps its hostnames, ports and Let's Encrypt certificates, so no new certificates are requested, and its sites are unavailable for a few seconds. The upgrade moves a host's instances together or not at all: it refuses the whole host, upgrades none of its instances, and says why, if the instances use both Docker and Podman, the CLI cannot write to an instance's directory, rootless Podman lacks the operator's systemd user session, a setting is invalid, or two instances would clash at the edge. If moving an instance fails, its docker-compose.yml, .env and config/Caddyfile are restored, it comes back on its own Caddy as before, and it is not upgraded. See New and existing instances for the full rules.

The upgrade also renames the TLS settings in each instance's .env: CADDY_TLS_MODE becomes TLS_MODE, CADDY_AUTO_HTTPS=off becomes TLS_MODE=off, and CADDY_TRUSTED_PROXIES, CADDY_TLS_CERT and CADDY_TLS_KEY become TRUSTED_PROXIES, TLS_CERT and TLS_KEY. A gitops repository's env.template can keep the old names.

Canasta CLI 4.25.1 changes how Kubernetes pods are replaced: web, Varnish and Caddy pods finish the requests they are serving before they stop, and a replacement pod is ready before the old one goes, so later rollouts no longer drop requests. With CrowdSec enabled, its local API also moves out of the Caddy pod into a Deployment of its own, keeping its volume, so the bouncer, its decisions and the Central API registration carry over with nothing to re-enroll. These changes roll the instance's pods once, at the first deploy after the upgrade: the upgrade itself when the image tag changes, otherwise the next canasta restart, or, on a gitops-managed instance, the sync after the push. That first rollout replaces pods that lack the new shutdown handling, so it can still interrupt requests for a couple of seconds; later rollouts do not.

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 --apply

For example, Canasta CLI 4.21.0 ships a config/default.vcl that no longer lets client requests trigger Varnish cache bans; instances created earlier keep the old file until you adopt the new one this way (see Varnish and cache purges).

The command is read-only unless --apply 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 — --apply replaces your local edits to that file. Rendered files (.env, config/wikis.yaml, the Caddyfile) are not refreshed here — canasta reconcile renders those — and per-wiki Settings.php is yours and is never overwritten.

GitOps-managed Kubernetes instances

On a Kubernetes instance managed through gitops, Argo CD deploys the instance from its gitops repository. As of Canasta CLI 4.25.0, canasta upgrade stages the refreshed chart and image tag in that repository instead of redeploying the instance, and ends with the commands that deploy it: 

canasta gitops push -i <id>
canasta gitops sync -i <id>

An instance that was stopped is left stopped; run canasta gitops push, and the upgrade deploys the next time it starts. An instance built from source still has its image rebuilt, and its web pods restart when the new build differs from the image they run. The summary at the end names the instances waiting for a push.

The upgrade also moves each such instance's Argo CD Application into a project of its own; see GitOps.

Composer configuration

As of Canasta 3.5.28, the image keeps its own list of the bundled extensions and skins that need Composer, and the instance's config/composer.local.json holds only your additions (see Composer dependencies). Bundled extensions and skins used to be listed in config/composer.local.json, but they are no longer needed there. Once a running instance's web container is on Canasta 3.5.28 or later, canasta upgrade removes the entries for bundled extensions and skins from that file, along with entries for extensions that used to be bundled but no longer are. Everything else in the file is kept. The upgrade names what it removed, and deletes the file if nothing of yours is left. On a gitops-managed instance the change is staged; publish it with canasta gitops push. (A gitops-managed Kubernetes instance reaches the new image only through the push and sync described above, so its file is tidied by the next canasta upgrade after that.)

If the web container's startup composer update fails, the container usually still starts on the image's bundled packages, but the packages you added are not installed. canasta start, canasta restart and canasta upgrade print a warning with the first line of the failure and the command that shows the full record, which is kept in config/persistent/composer-update.failed; canasta doctor reports it too.

Reclaiming disk after an upgrade

Every upgrade pulls a new Canasta image (and rebuilds any build: sidecars), but the images and layers it supersedes are left on the host. Over several upgrades these accumulate and can eventually fill the disk — sometimes during an upgrade itself. Pass --purge to reclaim that space automatically once the upgrade completes: 

canasta upgrade --purge

On each upgraded host, --purge:

  1. Removes the ghcr.io/canastawiki/canasta image tags the upgrade superseded — but only those no container or pod still references, so an image another instance on the same host is still running is left untouched.
  2. Prunes dangling image layers left behind by rebuilding build: sidecars.
  3. On Kubernetes, additionally prunes container images no pod references and garbage-collects the in-cluster image registry.

It is deliberately conservative: it never removes an image still in use and never touches volumes, so it is safe to run on a host with several instances. This is different from running docker system prune --all --volumes yourself, which can delete a stopped instance's image or its data volumes. The purge runs once per host after all of that host's instances have upgraded.

Combine it with --dry-run to see which hosts would be purged without changing anything: 

canasta upgrade --dry-run --purge

MediaWiki's own database account

As of Canasta CLI 4.22.0 on Docker Compose and 4.25.2 on Kubernetes, MediaWiki connects to the bundled database with its own mediawiki account instead of the database's root account. The account has full access to the instance's wiki databases only: each wiki's own database plus the extra databases it declares (see extra databases). The web container no longer receives the root password. See Database accounts for the keys involved.

New instances get the account when they are created. canasta upgrade moves existing instances to it after their restart, reporting: 

MediaWiki now connects as 'mediawiki', with access to this instance's wiki databases only; the root password is no longer in the web container.

On a Kubernetes instance that is not gitops-managed, the move redeploys the instance as a rolling update, so the wiki keeps serving while its web pods are replaced. The new pods' ensure-db-account init container creates the account and grants it the wiki databases before MediaWiki starts.

An instance is moved only when it is running, uses the bundled database, and still connects as root. An instance that is stopped during the upgrade is moved by the next upgrade that finds it running. Instances on an external database are not affected.

When an instance stays on root. The upgrade leaves an instance on the root account, and says why, when switching would cut a wiki off from its data:

  • A settings file sets $wgDBuser or $wgDBpassword. Such a setting overrides the account, so remove it.
  • The database server holds a database that no wiki declares, such as a Cargo database set only through $wgCargoDBname. Declare each database a wiki uses with canasta backup databases add, and drop any that are no longer used.

The move is tried again on the next upgrade. If anything fails after the switch, the upgrade puts the instance back on the root account.

GitOps-managed instances. On Docker Compose, the move records the new keys in this host's gitops vars. Run canasta gitops push afterwards so they are committed before the next pull.

On a gitops-managed Kubernetes instance, the move is staged with the rest of the upgrade (see GitOps-managed Kubernetes instances). The upgrade adds the account's password to the instance's db Secret and selects the account in this host's gitops vars, and MediaWiki moves to it when you run canasta gitops push and canasta gitops sync. canasta gitops push refuses to publish values that select the account while the db Secret has no WIKI_DB_PASSWORD key.

Staying on the root account. To keep an instance on root, set CANASTA_DB_ROOT_ACCOUNT=true. Upgrades then leave it alone, and an instance that has already been moved goes back to root at its next restart (on a gitops-managed Kubernetes instance, at the push and sync): 

canasta config set -i <id> CANASTA_DB_ROOT_ACCOUNT=true

Unset it to let the next upgrade move the instance again. On Kubernetes, that move reuses the account password the instance's db Secret already holds, if it has one.

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.

Crossing a major version

By default canasta upgrade stays within your current major version — it upgrades to the highest vX.Y.Z release whose major matches what you have installed, so it never jumps to a new major on its own. To move to the latest release overall, including a new major version, pass --allow-major: 

canasta upgrade --allow-major

A new major version may include breaking changes, so review the release notes before crossing a major boundary.

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).
  3. Check for extensions the new image no longer includes. A wiki that loads an extension the new image no longer includes fails to start, and the error names the extension. Disable it before upgrading — globally, and with -w for each wiki that enables it on its own — or add it under the instance's extensions/ directory:
   canasta extension disable <name>
  1. If a settings file under config/settings/ loads it with wfLoadExtension(), remove that line instead. Check the Canasta release notes for extensions a release removes.

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.

ℹ️ Note: If canasta upgrade fails here with CLI update failed: failed to download install script: HTTP 404, your Go binary predates the self-update mechanism that reaches the final release. Skip this step and install the current CLI directly using the command in [[#Step 2: Run any canasta command to see migration instructions|Step 2]] below. Your registered instances are unaffected.

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.

ℹ️ Note: The first canasta upgrade you run from the current CLI on a legacy instance whose bundled database still runs MySQL 8.0 also migrates that database in place to MariaDB (a dump and reload). Verify your pre-upgrade backup exists first, and allow extra downtime and free disk space proportional to the database size.

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.

Retrieved from "https://canasta.wiki/w/index.php?title=Help:Upgrading&oldid=1507"
Powered by MediaWiki
Powered by Canasta