Canasta requires the use of Docker, and then additionally either Docker Compose or Kubernetes as an orchestration framework. For most users, Docker Compose is the best choice; the following instructions are specifically for the use of Docker Compose.
You should have both Docker Engine and Docker Compose installed. This is very fast and easy to do on common Linux distributions such as Debian, Ubuntu, Red Hat, and CentOS. By installing Docker Engine from apt or yum, you get Docker Compose along with it. See the following install guides for each OS:
The easiest, and recommended, approach to set up Canasta installations is to use the Canasta CLI (command-line interface). It lets you install and use Canasta without having to know anything about Docker or Docker Compose. Then, once it is installed, the CLI can be used to easily create, import, start, stop, manage extension/skins, and back up Canasta installations.
The following covers the installation, and a few of the commands, of the Canasta CLI. For complete documentation on the CLI, visit the CLI page.
curl -fsL https://raw.githubusercontent.com/CanastaWiki/Canasta-CLI/main/install.sh | bashsudo canasta create -i canastaId -n example.com -w Canasta Wiki -a admin -o docker-composesudo canasta import -i importWikiId -d ./backup.sql.gz -e ./.env -l ./LocalSettings.php sudo canasta extension enable Bootstrap -i canastaIdsudo canasta skin enable Vector -i canastaIdhttps://github.com/CanastaWiki/Canasta-DockerCompose and cd into that directory.env.example to .env and customize as needed (more details on how to configure it are in the Configuration section).sql or .sql.gz file) into the _initdb/ directoryLocalSettings.php in the config/ directory and change your database configuration to be the following:dbrootmediawiki (by default; see Configuration section)docker-compose up -dhttp://localhost if installed locally)https://github.com/CanastaWiki/Canasta-DockerCompose and cd into that directory.env.example to .env and customize as needed (more details on how to configure it are in the Configuration section)docker-compose up -dhttp://localhost if installed locally) and run the MediaWiki setup wizard with the following info:dbrootmediawiki (by default; see Configuration section)LocalSettings.php in the config/ directorycfLoadSkin( 'Vector' ); to enable the Vector skin, cfLoadExtension( 'VisualEditor' ); for VisualEditor, etc. (More information about installing extensions can be found at the extensions setup page.)docker-compose down, then docker-compose up -d (this is important because it initializes your LocalSettings.php for Canasta)http://localhost if installed locally)There's several things you can do to polish up your wiki so it's ready for use:
cfLoadSkin call to LocalSettings.php. For instance, to install Vector, add: cfLoadSkin( 'Vector' ); to LocalSettings.php..php files in the config/settings/ directory will be loaded as if their contents were in LocalSettings.php. In addition, if you want to remove the Canasta footer icon, you can remove the config/settings/CanastaFooterIcon.php file.Canasta relies on setting environment variables in the Docker container for controlling
aspects of the system that are outside the purview of LocalSettings.php. You can change
these options by editing the .env file; see .env.example for details:
PORT - modify the publicly-accessible HTTP port, default is 80MYSQL_PASSWORD - modify MySQL container root user password, default is mediawiki
(use it when installing the wiki via wizard)PHP_UPLOAD_MAX_FILESIZE - php.ini upload max file sizePHP_POST_MAX_SIZE - php.ini post max sizeYou can add/modify extensions and skins using the following mount points:
./config - persistent bind-mount which stores the LocalSettings.php file,
volumed in as mediawiki/config/LocalSettings.php -> /var/www/mediawiki/w/LocalSettings.php./images - persistent bind-mount which stores the wiki images,
volumed in as mediawiki/images -> /var/www/mediawiki/w/images./skins - persistent bind-mount which stores 3rd party skins,
volumed in as /var/www/mediawiki/w/user-skins./extensions - persistent bind-mount which stores 3rd party extensions,
volumed in as /var/www/mediawiki/w/user-extensions./_initdb - persistent bind-mount which can be used to initialize the database container
with a mysql dump. You can place .sql or .gz database dump there. This is optional and
intended to be used for migrations only.In LocalSettings.php you can add an extension by picking its name from our list of bundled extensions and add a cfLoadExtension, e.g.:
cfLoadExtension( 'Cite' );In LocalSettings.php you can add a skin by picking its name from our list of bundled skins and add a cfLoadSkin call, e.g.:
cfLoadSkin( 'Timeless' );In order to install a 3rd party extension, simply place it in the ./extensions
directory and add a wfLoadExtension call to ./config/LocalSettings.php, e.g.:
wfLoadExtension( 'MyCustomExtension' );If a 3rd party extension requires some Composer packages to be installed, just
add a line for the extension's composer.json file to the
config/composer.local.json file, e.g.:
{
"extra": {
"merge-plugin": {
"include": [
"user-extensions/SomeExtension/composer.json"
]
}
}
}Note: the require section of config/composer.local.json is ignored; thus
you won't be able to install new extensions via Composer, only dependencies.
In order to install a 3rd party skin, simply place it in the ./skins
directory and add a wfLoadSkin call to ./config/LocalSettings.php, e.g.:
wfLoadSkin( 'MyCustomSkin' );Canasta offers Kubernetes support for heavy-duty wikis needing the power provided by Kubernetes. However, it is not for the faint of heart. We recommend smaller wikis use Docker Compose to manage their stack.
To use Kubernetes, first make sure you have a Kubernetes cluster ready, and that Kubectl works.
Then, clone the repository:
git clone https://github.com/CanastaWiki/Canasta-KubernetesMake necessary changes to the .env file and the files in the config and settings directory, and then call the following:
./start.sh