Source: Dev.to

---

⚠️ Collection Error: Content refinement error: Error: 429 429 Too Many Requests: you (bkperio) have reached your weekly usage limit, upgrade for higher limits: https://ollama.com/upgrade

---

A complete guide to setting up Zoho Catalyst CLI using Docker on Windows (WSL2 + Ubuntu) Before starting, ensure you have the following: A Windows machine with WSL2 enabled

Ubuntu installed via WSL2 Docker installed on Ubuntu — see Step 2 A Zoho Catalyst account

Basic familiarity with the terminal You can access your Ubuntu environment in any of the following ways: Option 1 — Via the Ubuntu App: Press Windows + S and search for Ubuntu

Click to open it Option 2 — Via Windows Terminal, CMD or PowerShell: wsl

Option 3 — Via any terminal that supports WSL (e.g. Windows Terminal, Git Bash): wsl -d Ubuntu

In all cases you’ll see a terminal prompt like: username@DESKTOP-XXXX:~$

You are now inside your Ubuntu environment. Run the following commands in your Ubuntu terminal one by one:

Remove any old Docker versions

sudo apt-get remove -y docker docker-engine docker.io containerd runc

Update package index and install dependencies

sudo apt-get update sudo apt-get install -y ca-certificates curl gnupg lsb-release

Add Docker’s official GPG key

sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg |
sudo gpg —dearmor -o /etc/apt/keyrings/docker.gpg

Add the Docker repository

echo
“deb [arch=$(dpkg —print-architecture)
signed-by=/etc/apt/keyrings/docker.gpg]
https://download.docker.com/linux/ubuntu
$(lsb_release -cs) stable” |
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Install Docker Engine

sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Allow your user to run Docker without sudo

sudo usermod -aG docker $USER newgrp docker

Verify Docker is installed correctly: docker —version

mkdir ~/projects/catalyst cd ~/projects/catalyst

Create a file named Dockerfile inside ~/projects/catalyst: nano Dockerfile

Paste the following content:

Official Node.js LTS slim image — small footprint, Catalyst compatible

FROM node:20-slim

Set working directory inside the container

WORKDIR /app

Install Zoho Catalyst CLI globally

RUN npm install -g zcatalyst-cli

Drop into bash shell on container start

CMD [“bash”]

Save and exit (Ctrl+X, then Y, then Enter). Create a file named docker-compose.yml in the same folder: nano docker-compose.yml

Paste the following content: services: catalyst: build: . image: catalyst-cli stdin_open: true # keeps terminal interactive (-i) tty: true # allocates a terminal (-t) network_mode: host # required for OAuth login callback on localhost:9005 volumes: - .:/app # maps your project folder into the container

Save and exit (Ctrl+X, then Y, then Enter). Why network_mode: host? Zoho Catalyst’s login flow uses an OAuth callback on localhost:9005. Without host networking, Docker’s isolated network intercepts this callback and the login hangs. Host mode ensures the callback reaches the container correctly. docker build -t catalyst-cli .

Verify the image was created: docker images

You should see: REPOSITORY TAG IMAGE ID CREATED SIZE catalyst-cli latest xxxxxxxxxxxx x hours ago …

Save the image as a portable .tar file: docker save -o catalyst-cli.tar catalyst-cli

Why docker save? This bundles the entire image — all layers, metadata and installed CLI — into a single portable file you can share, store on a USB drive, or keep in cloud storage. Move it to your preferred storage location: mv catalyst-cli.tar /path/to/your/storage/

On any new machine, after installing Docker (Steps 1–2), load the image from the .tar file: docker load -i /path/to/catalyst-cli.tar

Why docker load and not docker import? docker load fully restores the image with all layers and tags intact. docker import loses layer history and is meant for raw filesystem snapshots only. docker compose run catalyst

You are now inside the container. Your terminal prompt will change to: root@your-machine:/app#

catalyst login

A browser window will open automatically Log in with your Zoho account Once logged in, return to the terminal — it should confirm successful authentication catalyst init

Follow the prompts to: Select your Zoho organisation Select or create a Catalyst project Choose your project directory Every time you want to work on your Catalyst project:

1. Navigate to your project folder

cd ~/projects/catalyst

2. Start the container

docker compose run catalyst

3. Login

catalyst login

4. Work on your project

catalyst init # first time only catalyst serve # start local dev server

~/projects/catalyst/ ├── Dockerfile ← defines the container environment ├── docker-compose.yml ← defines how the container runs └── catalyst-cli.tar ← portable reusable image (move to storage)

Issue Cause Fix

catalyst login hangs OAuth callback port not reachable Ensure network_mode: host is in docker-compose.yml

ERR_EMPTY_RESPONSE in browser Port not mapped correctly Use —network host or network_mode: host

docker: command not found Docker not installed Redo Step 2

permission denied running Docker User not in docker group Run sudo usermod -aG docker $USER && newgrp docker

Guide based on Ubuntu via WSL2 on Windows. Last updated March 2026.