Help:Installation
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 www-data groups, then log out and log back in:
sudo usermod -aG docker,www-data $USER
docker— permission to run Docker commands (replaces the need forsudo)www-data— permission to manage files in the installation'sconfig/directory (shared with the web container)
Without these groups, you will get "permission denied" errors when running CLI commands or editing configuration files.
Install
Run the automated installer (Linux/macOS):
curl -fsSL https://raw.githubusercontent.com/CanastaWiki/Canasta-CLI/main/install.sh | sudo bash
On Windows, use WSL (Windows Subsystem for Linux) and run the installer inside your WSL distribution.
Verify Installation
canasta version
Updating
The CLI automatically updates itself when you run canasta upgrade. This ensures you always have the latest CLI version when upgrading your Canasta instances.
Uninstall
First, delete any Canasta installations 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
Post-installation notes
Email configuration
Email works out of the box using a built-in mail server (Postfix). Messages may be flagged as spam by recipients since the server has no SPF or DKIM records. For production use, configure an authenticated SMTP provider via $wgSMTP. See the Email guide for details.
