Migrating an existing wiki to Canasta

This guide walks through migrating an existing MediaWiki installation to Canasta on a fresh VPS (Debian or Ubuntu).

Prerequisites

Docker

Install Docker Engine on your VPS:

curl -fsSL https://get.docker.com | sh

Add your user to the docker and www-data groups:

sudo usermod -aG docker,www-data $USER

Log out and back in for the group changes to take effect. Verify with:

groups

You should see both docker and www-data in the output.

Files and information

Have the following ready:

Item	Example	Notes
Instance ID	`wikifarm`	Alphanumeric, hyphens, and underscores. Must start and end with a letter or number.
Wiki ID	`main`	Alphanumeric and underscores only. No hyphens.
Domain name	`wiki.example.com`	The FQDN where the wiki will be served.
Database dump	`dump.sql` or `dump.sql.gz`	MySQL or MariaDB dump file.
Images archive	`images.tar.gz`	Tar file containing the contents of the old wiki's `images/` directory.
Settings files	`LocalSettings.php` or `settings.tar.gz`	Either a single `LocalSettings.php` file, or a tar file containing multiple PHP settings files.

Upload all files to the VPS (e.g., to /tmp/migration/).

Step 1: Install Canasta CLI

curl -fsL https://raw.githubusercontent.com/CanastaWiki/Canasta-CLI/main/install.sh | bash

Verify the installation:

canasta version

Step 2: Create the Canasta instance

canasta create -i wikifarm -w main -n wiki.example.com -d /tmp/migration/dump.sql

This will:

Create the installation directory at /home/user/wikifarm/ (or wherever you run the command)
Start the database, web server, and cache containers
Import your database dump
Generate a new $wgSecretKey

The admin credentials from your original wiki are preserved in the imported database — no new admin account is created.

Change into the instance directory so you can omit -i wikifarm from subsequent commands:

cd wikifarm

Step 3: Restore images

Stop the containers while restoring files:

canasta stop

Extract your images archive into the images/ directory:

tar xzf /tmp/migration/images.tar.gz -C images/

Make sure the files end up directly in images/ (not in a nested subdirectory like images/images/). Adjust the tar command if needed.

Step 4: Place settings files

Preparing your settings

Your old settings need to be adapted for Canasta. Remove the following, as Canasta handles them automatically:

Database connection settings ($wgDBserver, $wgDBname, $wgDBuser, $wgDBpassword)
$wgSecretKey and $wgUpgradeKey
$wgSitename (set via wikis.yaml)
$wgServer / $wgCanonicalServer (set via wikis.yaml)
$wgScriptPath (Canasta uses /w)
$wgArticlePath (Canasta uses /wiki/$1)
Any wfLoadExtension() or wfLoadSkin() calls for extensions and skins you plan to enable via canasta extension enable / canasta skin enable (see Step 5) — the CLI manages these through settings.yaml instead. Keep wfLoadExtension() calls for any extensions you prefer to manage manually.

Per-wiki settings

If you have a single LocalSettings.php:

cp /tmp/migration/LocalSettings.php config/settings/wikis/main/

If you have a tar file with multiple PHP settings files:

tar xzf /tmp/migration/settings.tar.gz -C config/settings/wikis/main/

All PHP files in this directory are loaded in alphabetical order.

Global settings

If you have settings that should apply to all wikis (relevant if you plan to add more wikis later), place them in the global settings directory instead:

cp /tmp/migration/SomeGlobalSettings.php config/settings/global/

Step 5: Enable bundled extensions and skins

Canasta bundles over 100 extensions and skins. Start the containers first:

canasta start

List what's available:

canasta extension list
canasta skin list

Enable the ones your wiki uses. For example:

canasta extension enable VisualEditor,Cite,ParserFunctions,CategoryTree
canasta skin enable Vector

You can enable multiple at once by separating names with commas. Extension and skin names are case-sensitive.

This updates config/settings/global/settings.yaml and automatically runs update.php to apply any database changes.

Step 6: Add non-bundled extensions and skins

If your wiki uses extensions or skins that are not bundled with Canasta, you need to install them manually.

Clone from git

cd extensions
git clone https://github.com/example/MyCustomExtension.git
cd ..

Or copy from a tar file

tar xzf /tmp/migration/MyCustomExtension.tar.gz -C extensions/

Load the extension

Create a PHP file in the per-wiki settings directory to load it:

cat > config/settings/wikis/main/MyCustomExtension.php << 'EOF'
<?php
wfLoadExtension( 'MyCustomExtension' );
EOF

If the extension needs configuration, add it to the same file:

cat > config/settings/wikis/main/MyCustomExtension.php << 'EOF'
<?php
wfLoadExtension( 'MyCustomExtension' );
$wgMyCustomSetting = true;
EOF

Repeat for each non-bundled extension or skin (use wfLoadSkin() for skins, and place them in the skins/ directory).

Composer dependencies

If a non-bundled extension requires Composer packages, add it to config/composer.local.json:

{
    "extra": {
        "merge-plugin": {
            "include": [
                "extensions/MyCustomExtension/composer.json"
            ]
        }
    }
}

Step 7: Run maintenance

Restart to pick up all the settings and extension changes:

canasta restart

Run the maintenance update sequence:

canasta maintenance update

This runs update.php (database schema updates), runJobs.php (pending jobs), and Semantic MediaWiki's rebuildData.php (if SMW is installed).

The SMW rebuild can take a long time on large wikis. To skip it and run it manually later:

canasta maintenance update --skip-smw

You can run the SMW rebuild separately when convenient:

canasta maintenance extension SemanticMediaWiki rebuildData.php

Step 8: Verify

Visit your wiki at https://wiki.example.com and check:

Pages load correctly
Images display
Special:Version shows expected extensions and skins
Log in with your old admin credentials

Post-migration

Once your wiki is running and verified, set up configuration management and backups.

GitOps (version-controlled configuration)

GitOps tracks your configuration in a git repository, making it easy to review changes, roll back, and replicate your setup on another server.

Create an empty repository on GitHub or GitLab (no README, no commits), then:

canasta gitops init -n myserver --repo git@github.com:yourorg/wikifarm-config.git --key ~/gitops-key

This initializes git, sets up encrypted secrets with git-crypt, converts user-installed extensions and skins to submodules, and pushes to the remote. Store the exported key file securely — it is needed to set up additional servers.

After making configuration changes, push them with:

canasta gitops push

See GitOps guide for full documentation including multi-server deployments and pull request workflows.

Backups

Canasta uses Restic for encrypted, deduplicated backups. Backups can be stored on a local filesystem, AWS S3, or other cloud storage.

Add the backup configuration to your .env file:

canasta config set RESTIC_REPOSITORY=s3:s3.us-east-1.amazonaws.com/your-backup-bucket
canasta config set RESTIC_PASSWORD=your-encryption-password
canasta config set AWS_ACCESS_KEY_ID=your-access-key
canasta config set AWS_SECRET_ACCESS_KEY=your-secret-key

Initialize the backup repository and create your first backup:

canasta backup init
canasta backup create -t post-migration

Set up a daily backup schedule:

canasta backup schedule set --cron "0 2 * * *" -t daily

See Setting up AWS S3 for Canasta backups for detailed instructions on creating an S3 bucket with scoped permissions.

Troubleshooting

500 error after import

Check the web container logs:

canasta maintenance exec -- cat /var/log/apache2/error.log

Common causes:

Missing extension referenced in settings — remove the wfLoadExtension() call or install the extension
PHP syntax error in settings file

Database errors

If update.php reports errors, try running it directly for more verbose output:

canasta maintenance exec -- php maintenance/run.php update.php --schema --verbose

File permissions on images

If images don't display, fix ownership inside the container:

canasta maintenance exec -- chown -R www-data:www-data /var/www/mediawiki/images