Wiki lifecycle

From Canasta Wiki

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
-e Env file of settings for the instance's .env (see below)
-o Orchestrator: compose (default) or kubernetes

See the CLI reference for the full list of flags.

Settings from an env file

-e (--envfile) names a file of KEY=VALUE settings that canasta create writes into the instance's .env. Before it creates anything, create checks each setting as canasta config set does, and refuses an invalid value, such as an unknown TLS_MODE or a port that is not a number, with the same message. A key that config set does not know is written as is, with a warning, since an env file may carry settings of its own for a settings file or a sidecar:

Warning: CANASTA_ENABLE_ELASTICSERACH is not a known configuration key; it is written to .env as is.

On Kubernetes, the Docker Compose keys HTTP_PORT, HTTPS_PORT, TLS_MODE, TLS_MODE_HOSTS, TLS_CERT and TLS_KEY are written with a warning that they do not apply, so one env file can serve Compose and Kubernetes instances; their values are still checked. The cloudflare@ and imperva@ forms of TRUSTED_PROXIES are refused there. create sets COMPOSE_PROFILES itself, and says so if the env file sets it.

Importing an existing wiki while creating an instance

To migrate an existing MediaWiki instance into Canasta, prepare a database dump: a .sql file, plain or compressed with gzip, xz or zstd, 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.

On a gitops-managed Kubernetes instance, canasta add and canasta remove create or drop the wiki's databases but only stage the configuration change; deploy it with canasta gitops push and canasta gitops sync (see Applying changes on Kubernetes).

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 and any extra databases it declares (except one another wiki also declares), its settings files, uploaded images, and its entry in wikis.yaml. This works the same on an external database:

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. It also refuses when the instance is stopped, because its databases are dropped from inside the running instance; start it with canasta start and run remove again. To remove the last wiki, delete the instance instead (see Deleting an instance).

If a database can't be dropped, remove still removes the rest of the wiki and prints a warning naming the databases it left in place; drop them yourself once the cause is fixed.

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, .sql.xz or .sql.zst when importing), 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.

canasta create -d and canasta add -d load only the main dump. To bring a wiki with extra databases to a new instance, create the wiki from the main dump, declare each extra database, then import again so the extra dumps are loaded too:

canasta add -w docs -u example.com/docs -d ./docs.sql
canasta backup databases add -w docs docs_cargo
canasta import -w docs -d ./docs.sql

The second import reloads the main dump as well as docs.docs_cargo.sql. MediaWiki's own database account can't reach an extra database until it is declared (see Database accounts), so the wiki's Cargo data isn't available until the second step. On Kubernetes, the account gets the declared database when the instance next restarts.

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.

On Kubernetes, canasta delete likewise stops, leaving the instance registered, if the instance's namespace is still terminating after 10 minutes. Run delete again to finish the job, or pass --force to delete the instance anyway; any namespace that remains must then be removed by hand.

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.

canasta maintenance script, canasta maintenance extension and canasta maintenance update run their scripts as the web server user, www-data, on Docker Compose and Kubernetes alike, so the files they create stay writable by MediaWiki. canasta maintenance exec runs commands as root.

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

In a wiki farm, the script runs on every wiki unless you name one. Use -w (or --wiki) to target a specific wiki; --wiki docs and --wiki=docs both work:

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.