Canasta officially supports host systems which satisfy the following requirements:
Other similar systems may work, but are not supported.
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 | bash
sudo
usage).sudo canasta create -i canastaId -n example.com -w "Canasta Wiki" -a admin -o docker-compose
sudo canasta import -i importWikiId -d ./backup.sql.gz -e ./.env -l ./LocalSettings.php
sudo canasta extension enable Bootstrap -i canastaId
sudo canasta skin enable Vector -i canastaId
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).sql
or .sql.gz
file) into the _initdb/
directoryLocalSettings.php
in the config/
directory and change your database configuration to be the following:db
root
mediawiki
(by default; see Configuration section)docker-compose up -d
http://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 -d
http://localhost
if installed locally) and run the MediaWiki setup wizard with the following info:db
root
mediawiki
(by default; see Configuration section)LocalSettings.php
in the config/
directoryconfig/settings/
directory to enable the Vector skin by default, so your wiki will work right off the bat. But feel free to delete this if you are going to use another skin.wfLoadExtension( '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:
wfLoadSkin
call to LocalSettings.php
. For instance, to install Timeless, add: wfLoadSkin( 'Timeless' );
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 80
MYSQL_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 wfLoadExtension
, e.g.:
wfLoadExtension( 'Cite' );
As of Canasta 1.2.0, cfLoadExtension
has been retired in favor of wfLoadExtension
, which can now automatically detect and load an extension whether it's bundled or user-provided.
In LocalSettings.php
you can add a skin by picking its name from our list of bundled skins and add a wfLoadSkin
call, e.g.:
wfLoadSkin( 'Timeless' );
As of Canasta 1.2.0, cfLoadSkin
has been retired in favor of a wfLoadSkin
, which can now automatically detect and load a skin whether it's bundled or user-provided.
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' );
The United States Department of Defense (DoD) publicly releases a hardened version of Canasta, which means it's been specially patched and vetted to be secure enough for internal use in the U.S. military. While it might be a version or two behind, it has been cleared of security vulnerabilities by the DoD.
The hardened version of Canasta (Iron Bank Canasta) has significant internal changes made, but aims to replicate the functionality offered by the standard release. Changes notably include, but not limited to:
8080
instead of port 80
Canasta 1.2.0, MediaWiki 1.35.8: registry1.dso.mil/ironbank/opensource/canastawiki/canasta:1.35.8
Repository: https://repo1.dso.mil/dsop/opensource/canastawiki/canasta
Disclaimer: The U.S. Department of Defense does not sponsor or endorse Canasta in any way, but is kind enough to make their hardened version of Canasta available to the public. Similarly, the Canasta Project does not offer any guarantees that Iron Bank Canasta will function the exact same way as standard Canasta. Neither the Canasta Project nor the DoD provides official support for Iron Bank Canasta.
Make an account on dso.mil
below, which requires MFA or DoD Common Access Card but is open to the public.
https://login.dso.mil/register
Once signed in, access Registry 1 to retrieve your username and personal CLI secret for Docker login. (This is analogous to a personal access token on GitHub.)
At top right, choose your profile > CLI secret > copy
In the terminal of your Docker environment, connect Docker with the registry:
docker login https://registry1.dso.mil/
The first time you run this, it will prompt for your username and password. Use the credentials from Step 2, with password='CLI secret' (i.e. the personal access token) from your user profile at https://registry1.dso.mil/.
Pull the images to your machine:
docker pull registry1.dso.mil/ironbank/opensource/canastawiki/canasta:1.35.6
docker pull registry1.dso.mil/ironbank/opensource/mariadb/mariadb:10.6.7
Change the image your orchestrator uses (by editing docker-compose.override.yml
if you use our Docker Compose stack) to the following:
web
: registry1.dso.mil/ironbank/opensource/canastawiki/canasta:1.35.8
db
: registry1.dso.mil/ironbank/opensource/mariadb/mariadb:10.6.7
For instance, the docker-compose.override.yml
file might look like this:
version: '3.7'
# The above version is the Docker Compose manifest's version, not the Canasta Docker Compose stack's version.
#
# --- Canasta Stack for Docker Compose ---
#
# If you need to make changes to the stack, make them here.
# Only edits to docker-compose.override.yml are officially supported by Canasta.
#
# Uncomment the commented services and add lines below them if you would like to make additional customizations to them.
services:
db:
image: registry1.dso.mil/ironbank/opensource/mariadb/mariadb:10.6.7
web:
image: registry1.dso.mil/ironbank/opensource/canastawiki/canasta:1.35.8
#elasticsearch:
#caddy:
#varnish:
Additional considerations, such as Apache now using port 8080
instead of 80
, should be made when adapting your wiki to using Iron Bank Canasta.
It will be necessary to repeat the above login steps for each new session to relogin.
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-Kubernetes
Make necessary changes to the .env file and the files in the config and settings directory, and then call the following:
./start.sh