Installation
This guide covers installing and uninstalling the Canasta command line interface (CLI).
Prerequisites
Docker Compose (default)
Before using the Canasta CLI, you must have both Docker Engine and Docker Compose installed.
Kubernetes (managed cluster)
To use Canasta with a CLI-managed Kubernetes cluster (canasta create -o k8s --create-cluster), you also need:
On macOS: brew install kubectl kind
On Linux: download the binaries from the links above or use your package manager.
Docker is still required since kind uses it to run cluster nodes. See the Orchestrators guide for full details.
Windows
On Windows, use WSL (Windows Subsystem for Linux) and install Docker Engine inside your WSL distribution.
macOS
Docker Desktop for macOS includes Docker Engine and Docker Compose.
Linux
Linux is the most-tested and preferred OS environment as the host for Canasta. Installing the requirements is fast and easy to do on common Linux distributions such as Debian, Ubuntu, Red Hat, and CentOS. While you can get up and running with all the Docker requirements by installing Docker Desktop on Linux, if you are using a 'server environment' (no GUI), the recommended way to install is to uninstall any distribution-specific software and install Docker software using the Docker repositories. (The link is the install guide for Docker Compose which will also install the Docker Engine.)
Essentially, preparing your Linux server to be a Canasta host by installing the Docker suite of software includes something like
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin once you've
added the Docker repositories to your system.
Warning: Linux required group membership
Add your user to the docker and web server groups, then log out and log back in. On Debian and Ubuntu, the web server group is www-data:
sudo usermod -aG docker,www-data $USER
docker— permission to run Docker commands (replaces the need forsudo)- Web server group (e.g.
www-data) — permission to manage files in the instance'sconfig/directory (shared with the web container)
The web server group name varies by Linux distribution (e.g. http on Arch Linux, apache on RHEL/CentOS). See the Troubleshooting page for a full list.
Without these groups, you will get "permission denied" errors when running CLI commands or editing configuration files.
Install
Run the automated installer:
curl -fsSL https://raw.githubusercontent.com/CanastaWiki/Canasta-CLI/main/install.sh | sudo bash
ℹ️ Note: Running Canasta CLI commands does not require sudo. The only step that requires sudo is installing the CLI binary to /usr/local/bin/. On Linux, ensure your user is in the docker and web server groups (see Installation) so that CLI commands work without elevated privileges.
Verify installation
After installing, verify that the CLI is available and check its version:
canasta version
This prints the installed CLI version and confirms it is on your PATH. If you get "command not found", ensure /usr/local/bin is in your PATH or check that the binary was downloaded and moved correctly.
You can also run canasta help to see the full list of available commands.
Once verified, see the Quick start guide to create your first wiki.
Upgrading
Running canasta upgrade upgrades the entire Canasta stack. This includes pulling updated CanastaBase and Canasta Docker images (which contain MediaWiki, bundled extensions, and skins) and automatically updating the CLI binary itself.
When new Long Term Support (LTS) versions of MediaWiki are released, this is also how that upgrade is performed — by upgrading to a new version of CanastaBase that includes the updated MediaWiki version. Database schema changes are applied automatically via update.php on the next container start.
See the Upgrading guide for pre-upgrade steps, backup recommendations, and the full upgrade process.
Uninstall
First, delete any Canasta instances using canasta delete for each one.
Then remove the CLI binary and its configuration directory:
sudo rm /usr/local/bin/canasta
The configuration directory location depends on your platform:
- Linux (root):
sudo rm -r /etc/canasta - Linux (non-root):
rm -r ~/.config/canasta - macOS:
rm -r ~/Library/Application\ Support/canasta
