Help:Common tasks

This page covers common tasks for managing Canasta installations, including importing wikis, running maintenance scripts, configuring logos, and deployment options.

Default permissions

New Canasta installations include a config/settings/global/DefaultPermissions.php file that makes all wikis private by default. The file contains:

<?php
$wgGroupPermissions['*']['read'] = false;
$wgGroupPermissions['*']['edit'] = false;
$wgGroupPermissions['*']['createaccount'] = false;

This prevents anonymous users from reading, editing, or creating accounts on any wiki in the installation.

Making a wiki public

The three permissions control different levels of access for anonymous (logged-out) users:

• read — view pages. Set to true to make the wiki publicly readable.
• edit — edit pages. Most public wikis leave this false so that only registered users can make changes.
• createaccount — register new accounts. Set to true if you want anyone to be able to sign up. Leave false if administrators should control who gets an account.

To make all wikis publicly readable, edit config/settings/global/DefaultPermissions.php and change the permissions you want to allow. For example, a common configuration for a public wiki that requires login to edit:

<?php
$wgGroupPermissions['*']['read'] = true;
$wgGroupPermissions['*']['edit'] = false;
$wgGroupPermissions['*']['createaccount'] = true;

To delete the file entirely is equivalent to setting all three to true (MediaWiki's built-in defaults).

To make a specific wiki public while keeping others private, create a per-wiki settings file:

<?php
// config/settings/wikis/{wiki-id}/Permissions.php
$wgGroupPermissions['*']['read'] = true;
$wgGroupPermissions['*']['createaccount'] = true;

Per-wiki settings are loaded after global settings, so they override the defaults for that wiki only. Permissions not listed in the per-wiki file keep the global value (in this example, edit remains false).

See the MediaWiki documentation for the full list of available permissions.

Importing an existing wiki

To migrate an existing MediaWiki installation 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.

To import a database into an additional wiki in an existing installation, use canasta add with the -d flag:

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

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 installation 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 installation 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. Wrap the script name and any arguments in quotes so they are passed as a single argument:

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 "rebuildrecentchanges.php" -w docs

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. Flags (-i, -w) come before the extension name; everything after is the script and its arguments — no quotes needed:

canasta maintenance extension SemanticMediaWiki rebuildData.php
canasta maintenance extension CirrusSearch UpdateSearchIndexConfig.php --reindexAndRemoveOk --indexIdentifier now

For large operations, pass script-specific options directly:

canasta maintenance extension SemanticMediaWiki rebuildData.php -s 1000 -e 2000

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.php

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

See the CLI Reference for more details.

Configuring logos

MediaWiki uses the $wgLogos configuration variable to set the wiki logo. See the MediaWiki documentation for details on logo sizes and formats.

There are two approaches to configuring logos in Canasta, depending on whether you want the logo to follow wiki permissions or be publicly accessible.

Option 1: Public assets directory (recommended for most cases)

Place your logo in the public_assets/ directory. This directory is organized by wiki ID, so each wiki has its own subdirectory:

cp /path/to/logo.png public_assets/{wiki-id}/logo.png

Then configure it in a per-wiki settings file:

<?php
# config/settings/wikis/{wiki-id}/Logo.php

$wgLogos = [
    '1x' => "/public_assets/logo.png",
];

The URL /public_assets/logo.png is automatically routed to the correct wiki's subdirectory based on the request's domain or path.

This approach:

• Always publicly accessible — works for both public and private wikis
• Works for wiki farms — each wiki has its own subdirectory
• Fast — served as static files without MediaWiki overhead
• Persists across upgrades — stored in a mounted volume

Use this option for private wikis that need a visible logo on the login page, or any wiki where you want fast, public access to the logo.

Option 2: Upload via MediaWiki

Upload your logo through MediaWiki's Special:Upload page, then reference it in a settings file:

<?php
# config/settings/wikis/{wiki-id}/Logo.php

$wgLogos = [
    '1x' => $wgUploadPath . '/Logo.png',
];

This approach:

• Follows wiki permissions — on public wikis, anyone can see the logo; on private wikis, only logged-in users can see it
• Works for wiki farms — each wiki uploads its own logo
• Persists across upgrades — uploaded files are stored in the images/ directory

Use this option for fully private wikis where the logo should not be visible to logged-out users.

Summary

Scenario	Solution
Public wiki	Either option works
Private wiki, logo visible on login page	Public assets directory
Private wiki, logo hidden from logged-out users	Upload via MediaWiki

Deploying behind a reverse proxy

When running Canasta behind an external reverse proxy that terminates SSL and forwards requests to Canasta over HTTP (such as nginx, a cloud load balancer, or Cloudflare in "Flexible SSL" mode), you must tell Caddy to serve over HTTP only. Otherwise, Caddy will attempt to provision certificates and listen on HTTPS, causing redirect loops or connection errors.

For a new installation, create an env file with the setting and pass it to canasta create:

CADDY_AUTO_HTTPS=off

canasta create -i myinstance -w main -n example.com -e custom.env

This generates a Caddyfile with http:// site addresses so Caddy listens on port 80 only.

For an existing installation:

canasta config set CADDY_AUTO_HTTPS=off

To re-enable automatic HTTPS (e.g., if you move the wiki off the reverse proxy):

canasta config unset CADDY_AUTO_HTTPS

Changing the domain name

The domain name for each wiki is stored in config/wikis.yaml. The .env file also contains two domain-related variables:

• MW_SITE_SERVER — the full URL of the primary wiki (e.g., https://example.com)
• MW_SITE_FQDN — the domain name of the primary wiki (e.g., example.com)

These refer specifically to the primary (first) wiki in the installation. In a wiki farm, additional wikis may use the same domain (path-based) or different domains (subdomain-based), and their URLs are managed entirely in wikis.yaml.

Single wiki or path-based farm

When all wikis share the same domain, changing the domain requires updating both wikis.yaml and .env:

1. Edit config/wikis.yaml and update the url field for each wiki:

   wikis:
   - id: main
     url: newdomain.example.com
     name: main
   - id: docs
     url: newdomain.example.com/docs
     name: docs

1. Update the .env variables to match and restart:

   canasta config set MW_SITE_SERVER=https://newdomain.example.com MW_SITE_FQDN=newdomain.example.com

  This triggers a restart, which regenerates the Caddyfile from the updated wikis.yaml.

Subdomain-based farm

When wikis use different subdomains, you only need to update MW_SITE_SERVER and MW_SITE_FQDN if the primary wiki's domain is changing. To change another wiki's domain, edit its url in wikis.yaml and restart:

canasta restart

Port changes

If you are also changing the port, use canasta config set HTTPS_PORT=<port> instead — it updates wikis.yaml, MW_SITE_SERVER, and MW_SITE_FQDN automatically. See Running on non-standard ports.