Installation
This guide covers installing the Canasta command line interface (CLI). Canasta CLI 4.0.0 is a python/Ansible implementation. (The earlier Go implementation, Canasta-CLI 3.x, has been superseded — see Help:Upgrading if you have an existing Go-based install.)
The installer offers two modes:
- Docker mode (default) — the simplest setup. Only Docker is required on the host. The wrapper pulls a Canasta CLI Docker image and runs Ansible inside it.
- Native mode — installs Ansible directly on the host (in a Python virtual environment). Faster startup and easier to read or customize playbooks. Requires Python 3.10+ and git.
Prerequisites
Docker mode (default)
Only Docker Engine is required. Docker Compose is bundled with recent Docker installs.
Native mode
Native mode requires:
- Python 3.10+
- git
Ansible itself is installed automatically by the installer into a Python virtual environment — you do not need to install Ansible separately.
On Linux, the installer auto-installs git, python3, and python3-venv via apt-get / dnf / yum if they are missing. On macOS, install them yourself first (e.g. brew install python3 git).
Kubernetes (optional)
To manage Canasta instances on Kubernetes, also install:
You can verify dependencies after install using canasta doctor. See the Orchestrators guide for full Kubernetes setup details.
Windows
On Windows, use WSL (Windows Subsystem for Linux) and run the installer inside your WSL distribution. Docker mode is recommended.
macOS
Docker Desktop for macOS includes Docker Engine and Docker Compose. For native mode, install Python 3.10+ and git via Homebrew.
Linux
Linux is the most-tested host environment for Canasta. The installer auto-installs system dependencies via apt-get / dnf / yum.
The simplest way to install Docker Engine is the official convenience script:
curl -fsSL https://get.docker.com | sh
For more control over the install (e.g., production deployments where you want to pin specific package versions), use the official Docker repositories instead:
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Warning: Linux requires group membership
After installing, 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
The native installer creates a canasta system group and adds the current user to it; you'll also need docker and the web server group.
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) canasta(native install only) — permission to read and modify files under the Canasta install directory
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
Docker mode (default)
curl -fsSL https://get.canasta.wiki | bash
This installs the canasta-docker wrapper at /usr/local/bin/canasta-docker and a canasta symlink that points at it. The wrapper pulls a Canasta CLI Docker image on first use.
Native mode
curl -fsSL https://get.canasta.wiki | bash -s -- --native
This clones the Canasta CLI repository into /opt/canasta-ansible (Linux) or ~/canasta-ansible (macOS), creates a Python virtual environment, installs Ansible into it, and creates symlinks at /usr/local/bin/canasta-native and /usr/local/bin/canasta.
ℹ️ Note: Running Canasta CLI commands does not require sudo. On Linux, ensure your user is in the docker and web server groups (and the canasta group for native installs) so that CLI commands work without elevated privileges.
Switching between Docker and native modes
Both wrappers can coexist on the same machine. If you installed in Docker mode, you can also install native mode (or vice versa) and switch between them at any time by re-pointing the canasta symlink:
# use Docker mode
sudo ln -sf /usr/local/bin/canasta-docker /usr/local/bin/canasta
# use native mode
sudo ln -sf /usr/local/bin/canasta-native /usr/local/bin/canasta
Your registered instances and their data are not affected by the switch — the registry (conf.json) and instance directories are independent of which wrapper invokes the CLI.
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.
You can also run canasta doctor to verify all required and optional dependencies are installed correctly on the target host:
canasta doctor
Once verified, see the Quick start guide to create your first wiki.
Upgrading
To upgrade an existing Canasta CLI install (4.0.0 or later), run:
canasta upgrade
This pulls the latest playbooks (native mode) or the latest Canasta CLI Docker image (Docker mode), then upgrades all registered Canasta instances — refreshing configs, pulling the latest Canasta image, running migrations, and restarting containers. Database schema changes are applied automatically via update.php on the next container start.
If you are upgrading from the older Go-based Canasta-CLI 3.x, see the Upgrading guide for the bridge release flow.
Uninstall
First, delete any Canasta instances using canasta delete for each one.
Then remove the CLI:
Docker mode
sudo rm /usr/local/bin/canasta /usr/local/bin/canasta-docker
Native mode
sudo rm /usr/local/bin/canasta /usr/local/bin/canasta-docker /usr/local/bin/canasta-native
sudo rm -rf /opt/canasta-ansible # Linux
rm -rf ~/canasta-ansible # macOS
The configuration directory is preserved in case you reinstall. To remove it as well:
- Linux (root):
sudo rm -r /etc/canasta - Linux (non-root):
rm -r ~/.config/canasta - macOS:
rm -r ~/Library/Application\ Support/canasta
