Wiki lifecycle

This page covers the full lifecycle of a Canasta instance: creating wiki farms, adding and removing wikis, importing existing databases, running maintenance scripts, and deleting instances.

Creating an instance

Use canasta create to create a new Canasta instance. At minimum, you need an instance ID, a wiki ID, and a server name:

canasta create -i myinstance -w main -n example.com

This creates a single-wiki instance. The installer runs automatically, generating an admin account (default: WikiSysop) and printing the password.

To create a wiki farm from the start, add more wikis after creation with canasta add (see below).

Common flags

Flag	Description
`-i`	Instance ID (used to identify the instance)
`-w`	Wiki ID for the first wiki
`-n`	Server name (domain)
`-a`	Admin username (default: WikiSysop)
`-d`	Database dump to import instead of running the installer
`-o`	Orchestrator: `compose` (default) or `kubernetes`

See the CLI reference for the full list of flags.

Importing an existing wiki while creating an instance

To migrate an existing MediaWiki instance into Canasta, prepare a database dump (.sql or .sql.gz file) and pass it with the -d flag:

canasta create -i myinstance -w main -n example.com -d ./backup.sql.gz

You can also provide a per-wiki settings file and an environment file with password overrides:

canasta create -i myinstance -w main -n example.com -d ./backup.sql.gz -l ./my-settings.php -e ./custom.env

The -l flag (--wiki-settings) copies the specified file to config/settings/wikis/{wiki-id}/, preserving the filename. Use it to bring over custom settings from an existing wiki.

See the CLI Reference for the full list of flags.

Adding a wiki

Use canasta add to add a wiki to an existing instance, turning it into a wiki farm (or adding to an existing farm). Each wiki needs a wiki ID and a URL:

canasta add -w docs -u example.com/docs

This registers the new wiki in wikis.yaml, regenerates the Caddyfile, and runs the MediaWiki installer for the new wiki.

Path-based vs. subdomain-based wikis

Wikis can be accessed by path or by subdomain:

# Path-based: same domain, different path
canasta add -w docs -u example.com/docs

# Subdomain-based: different domain
canasta add -w blog -u blog.example.com

See Wiki farms for more on farm architectures.

Importing an existing wiki while adding

To add a wiki with an existing database dump instead of running the installer:

canasta add -w docs -u example.com/docs -d ./docs-backup.sql.gz

See the CLI reference for the full list of flags.

Removing a wiki

Use canasta remove to remove a wiki from an instance. This deletes the wiki's database, settings files, uploaded images, and its entry in wikis.yaml:

canasta remove -w docs

You will be prompted for confirmation before any data is deleted. Use -y to skip the prompt:

canasta remove -w docs -y

⚠️ Warning: This permanently deletes the wiki's database and files. Make sure you have a backup if you might need the data later.

Before deleting anything, canasta remove checks that the wiki ID is valid, that the wiki exists in wikis.yaml, and that it is not the instance's only wiki. To remove the last wiki, delete the instance instead (see Deleting an instance).

See the CLI reference for the full list of flags.

Exporting a wiki's database

Use canasta export to save a wiki's database as a SQL dump. The instance must be running. By default the dump is written to <wiki-id>.sql in the current directory; give an output path ending in .gz to compress it:

canasta export -w docs
canasta export -w docs -f docs-backup.sql.gz

The dump contains everything in the wiki's database, including user accounts and password hashes, so as of Canasta CLI 4.21.0 the file is created readable and writable by its owner only (mode 0600). Loosen the permissions yourself if someone else needs to read it.

To load a dump into an existing wiki, replacing its current database, use canasta import:

canasta import -w docs -d docs-backup.sql.gz

Extra databases. As of Canasta CLI 4.22.0, canasta export also exports each extra database the wiki declares (see Backing up extra databases), such as a Cargo database. Each goes to its own file beside the main dump, named <stem>.<database>.sql (or .sql.gz), where the stem is the output path without its extension. For example, canasta export -w docs with a declared docs_cargo writes docs.sql and docs.docs_cargo.sql. canasta import reads them from the same place, for each extra database the target wiki declares. It warns about a declared database with no dump file, and reports a dump file for a database the target wiki doesn't declare. The main dump names no database, so it can still be imported into a wiki with a different ID.

See the export and import CLI references for the full list of flags. For full-instance backups, use canasta backup instead.

Deleting an instance

Use canasta delete to permanently delete an entire instance. This stops and removes all containers and volumes, deletes all configuration files and data, and removes the instance from the Canasta registry:

canasta delete

You will be prompted for confirmation. Use -y to skip the prompt:

canasta delete -y

⚠️ Warning: This permanently deletes all wikis, databases, uploaded files, and configuration in the instance. This action cannot be undone. Make sure you have a backup before proceeding.

As of Canasta CLI 4.22.0, canasta delete on Docker Compose stops if it cannot remove the instance's containers and volumes. For example, the container runtime may be unreachable, or another container may still be using one of the volumes. In that case the instance stays registered and its files are left untouched, so you can fix the cause and run delete again. If the runtime is gone for good, --force deletes the instance anyway and warns about anything that may be left behind.

See the CLI reference for the full list of flags.

Maintenance scripts

MediaWiki includes over 200 maintenance scripts for tasks like changing passwords, importing images, and managing the database.

Automatic maintenance

You generally do not need to run maintenance scripts manually:

update.php runs automatically during container startup. If you need to run it, simply restart the instance with canasta restart.
runJobs.php runs automatically in the background for the entire life of the container.

Running the update sequence

Use canasta maintenance update to run the standard update sequence: update.php, runJobs.php, and (if Semantic MediaWiki is installed) rebuildData.php. Each script runs separately with its output streamed in real time.

canasta maintenance update

In a wiki farm, use -w to target a specific wiki. Without -w, the command runs on every wiki:

canasta maintenance update -w docs

If the instance has only one wiki, it is selected automatically.

Use --skip-jobs and --skip-smw to skip individual steps:

# Run only update.php
canasta maintenance update --skip-jobs --skip-smw

Running scripts manually

To run an arbitrary MediaWiki core maintenance script, use canasta maintenance script. Flags (-i, -w) come before the script name; everything after is the script and its arguments — no quotes needed:

canasta maintenance script createAndPromote.php WikiSysop MyPassword --bureaucrat --sysop

To list all available core maintenance scripts:

canasta maintenance script

Use -w to target a specific wiki in a farm:

canasta maintenance script -w docs rebuildrecentchanges.php

Running extension maintenance scripts

Many extensions include their own maintenance scripts (e.g., Semantic MediaWiki, CirrusSearch, Cargo). Use canasta maintenance extension to discover and run them.

List all loaded extensions that have maintenance scripts:

canasta maintenance extension

List available scripts for a specific extension:

canasta maintenance extension SemanticMediaWiki

Run an extension maintenance script by naming it as <ExtName>:<scriptName> (the .php suffix is dropped). Flags (-i, -w) come before it; anything after is passed to the script — no quotes needed:

canasta maintenance extension SemanticMediaWiki:rebuildData
canasta maintenance extension SemanticMediaWiki:rebuildData -s 1000 -e 2000
canasta maintenance extension CirrusSearch:UpdateSearchIndexConfig --reindexAndRemoveOk --indexIdentifier now

Use -w for wiki farms, just like other maintenance commands. Without -w, the command runs on all wikis:

canasta maintenance extension -w docs SemanticMediaWiki:rebuildData

Only extensions that are currently loaded (enabled) for the target wiki are shown and can be run.

See the CLI Reference for more details.