Documentation Download and setup CLI Data structures FAQ About

Canasta: Download and setup

Table of contents

Prerequisites

Canasta officially supports host systems which satisfy the following requirements:

Other similar systems may work, but are not supported.

Quick setup

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.

Before starting

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.

Installation

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

Create a new wiki

Import an existing wiki

Enable/disable an extension

Enable/disable a skin

Manual installation

Import existing wiki

Create new wiki

After installation

There's several things you can do to polish up your wiki so it's ready for use:

Configuration

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:

You can add/modify extensions and skins using the following mount points:

Enabling extensions

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.

Enabling skins

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.

Installing 3rd party extensions

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' );

Composer packages

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.

Installing 3rd party skins

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' );

Using hardened image (Iron Bank Canasta)

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:

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.

Setup instructions

Step 1:

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

Step 2:

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

https://registry1.dso.mil/

At top right, choose your profile > CLI secret > copy

Step 3:

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

Step 4:

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

Step 5:

Change the image your orchestrator uses (by editing docker-compose.override.yml if you use our Docker Compose stack) to the following:

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:

Step 6:

Additional considerations, such as Apache now using port 8080 instead of 80, should be made when adapting your wiki to using Iron Bank Canasta.

After initial setup

It will be necessary to repeat the above login steps for each new session to relogin.

Kubernetes

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
© 2022 Canasta Project