Zoho Catalyst CLI — Docker Setup Guide

A complete guide to setting up Zoho Catalyst CLI using Docker on Windows (WSL2 + Ubuntu)

Prerequisites

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

Step 1 — Open Ubuntu via WSL

You can access your Ubuntu environment in any of the following ways:

Option 1 — Via the Ubuntu App:

1. Press Windows + S and search for Ubuntu
   


2. 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.

Step 2 — Install Docker on Ubuntu

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

Step 3 — Create Your Project Structure

mkdir ~/projects/catalyst

cd ~/projects/catalyst

Step 4 — Create the Dockerfile

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).

Step 5 — Create the Docker Compose File

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.

Step 6 — Build the Docker Image

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    ...

Step 7 — Export the Image as a Reusable File

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/

Step 8 — Loading the Image on a New Machine

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.

Step 9 — Run the Container

docker compose run catalyst

You are now inside the container. Your terminal prompt will change to:

root@your-machine:/app#

Step 10 — Login to Zoho Catalyst

catalyst login

1. A browser window will open automatically


2. Log in with your Zoho account


3. Once logged in, return to the terminal — it should confirm successful authentication

Step 11 — Initialize Your Project

catalyst init

Follow the prompts to:

• Select your Zoho organisation


• Select or create a Catalyst project


• Choose your project directory

Daily Workflow

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

Project Structure Reference

~/projects/catalyst/

├── Dockerfile            ← defines the container environment

├── docker-compose.yml    ← defines how the container runs

└── catalyst-cli.tar      ← portable reusable image (move to storage)

Troubleshooting

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