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. Canasta does not support Podman on macOS.

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 Docker and, on Linux hosts, rootless Podman. On macOS, use Docker.

• 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, on Linux, 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

Debian 13 (trixie). Debian 13 ships podman-compose 1.3.0, which has a bug in ${VAR:-default} substitution that breaks Canasta's docker-compose.yml. After canasta install podman, install a fixed podman-compose with uv:

canasta install uv:podman-compose

uv:<tool> installs <tool> with uv (installing uv first if needed) and links it into /usr/local/bin, where it takes precedence over the distribution's copy in /usr/bin. canasta install uv installs uv on its own. Both are idempotent and take --host.

How the runtime is chosen

By default Canasta detects the runtime when canasta create sets up an instance, and the instance keeps that runtime for every later command. Docker is probed first: system Docker's /var/run/docker.sock if it exists and answers, then rootless Docker's docker.sock in $XDG_RUNTIME_DIR (typically /run/user/{uid}/). Only when neither is found does it use rootless Podman's podman/podman.sock there. If nothing is found it falls back to system Docker's default socket. canasta doctor reports which socket it found.

To choose the runtime yourself — for example on a host that has both — set CANASTA_CONTAINER_RUNTIME to docker or podman when you create the instance. Only that runtime is probed, and the command fails if it is not on the host instead of falling back to the other:

export CANASTA_CONTAINER_RUNTIME=podman
canasta create -i mysite -w main -n wiki.example.com

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's HAProxy edge listens on 443 and 80 by default, the latter for Let's Encrypt's ACME challenge and the HTTPS redirect. Under rootless Podman, the edge's systemd user socket unit, canasta-edge.socket, holds those ports and is subject to the same limit, so 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.

Host firewall

On Docker Compose, the only ports Canasta opens on the host are 80 and 443 (or each instance's HTTP_PORT and HTTPS_PORT), served by the HAProxy edge for every instance on the host. Each instance's Caddy publishes only loopback ports. The database, the web container, Varnish, Elasticsearch and any sidecars are reachable only on the instance's internal container network. Inbound, a Canasta host needs:

• 80/TCP and 443/TCP from the internet. Port 80 also serves Let's Encrypt's HTTP-01 challenge (not needed for that with TLS_MODE=acme-dns).
• 22/TCP for SSH, ideally limited to the addresses you administer from.

Canasta does not configure a firewall, so whether one is in place depends on your provider:

• AWS, Google Cloud and Azure block inbound traffic until you open it in a security group or firewall rule.
• Many VPS providers (Hetzner, DigitalOcean, Linode, Hostinger and others) leave every port open unless you enable their cloud firewall.

Where your provider offers a firewall, use it to allow only the ports above.

A host firewall such as ufw or firewalld still protects anything else running on the host, such as SSH. However, with Docker, ports that containers publish bypass ufw and firewalld rules. Docker inserts its own iptables rules, so closing 80 or 443 in ufw does not stop traffic to the edge. Rootless Podman forwards published ports through a process on the host, so host firewall rules do apply to it.

Kubernetes hosts expose more: the k3s API server, the kubelet and the pod network. See the host firewall section of the multi-node VPS journey.

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