Installation

This guide covers installing the Canasta command line interface (CLI). The Canasta CLI is a python/Ansible tool for managing Canasta instances. (If you have an older Go-based canasta binary installed, see Help:Upgrading for migration steps.)

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:

• kubectl — the Kubernetes command-line tool
• Helm 3.10+ — chart deployment

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 for sudo)
• Web server group (e.g. www-data) — permission to manage files in the instance's config/ 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.

Release vs development builds

By default the installer installs the latest released version of the Canasta CLI. To track the latest development build (the head of the main branch) instead, add --dev:

curl -fsSL https://get.canasta.wiki | bash -s -- --dev

This combines with either mode (--native or --docker). The same channel is used by canasta upgrade: a later canasta upgrade stays on the release channel, or canasta upgrade --dev to follow development builds. See Upgrading.

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.

Container runtime

The two installer modes above decide how the CLI runs. Which runtime the wiki's containers run on is a separate choice: on Docker Compose, Canasta supports both Docker and rootless Podman.

• Docker — the default, and the most widely tested path. Nothing extra to configure.
• Rootless Podman — runs the wiki's containers as an unprivileged user, with no daemon.

Kubernetes instances are unaffected by this choice; there the cluster's own container runtime applies.

Either wrapper can drive either runtime — canasta-docker runs its own image on Docker when present and falls back to Podman. The exception is canasta install itself, which does not work in canasta-docker mode at all: it configures host packages and systemd units, which cannot be done from inside a container. Install Podman with canasta-native, or by hand.

Installing Podman

canasta install podman

This installs Podman and podman-compose, enables systemd lingering for the operator user, and lowers the unprivileged port floor to 80. Lingering matters because without it systemd stops the wiki's containers as soon as the operator's login session ends. The command is idempotent — it skips a host that already has Podman — and takes --host for a remote target:

canasta install --host prod1.example.com podman

How the runtime is chosen

Canasta detects the runtime rather than taking a flag for it. On each target it probes $XDG_RUNTIME_DIR (typically /run/user/{uid}/) for a rootless socket, preferring Podman's podman/podman.sock and falling back to rootless Docker's docker.sock. If neither exists it uses system Docker's /var/run/docker.sock. canasta doctor reports which socket it found.

To point at a socket somewhere else, pass --docker-host:

canasta create -i mysite -w main -n wiki.example.com --docker-host unix:///run/user/1000/podman/podman.sock

Binding ports 80 and 443

A rootless container cannot bind a port below net.ipv4.ip_unprivileged_port_start, which most distributions default to 1024. Canasta needs both 443 and 80 — the latter for Let's Encrypt's ACME challenge — so canasta create fails its pre-flight check when the floor is higher, and canasta doctor reports Privileged ports: BLOCKED.

canasta install podman lowers the floor and persists it to /etc/sysctl.d/canasta-privport.conf so it survives a reboot. To do the same by hand:

sudo sysctl net.ipv4.ip_unprivileged_port_start=80

echo net.ipv4.ip_unprivileged_port_start=80 | sudo tee /etc/sysctl.d/canasta-privport.conf

The alternative is to leave the floor alone and serve the wiki on unprivileged ports instead — see Help:Running on non-standard ports, bearing in mind that automatic TLS needs port 80 reachable.

Upgrading

For routine upgrades, legacy Go-based-CLI migration, and migration of non-CLI instances, see Help:Upgrading.

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