DEV Community

Silly Coder
Silly Coder

Posted on

Zoho Catalyst CLI — Docker Setup Guide

#cli #docker #serverless #tutorial

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
Enter fullscreen mode Exit fullscreen mode

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

wsl -d Ubuntu
Enter fullscreen mode Exit fullscreen mode

In all cases you'll see a terminal prompt like:

username@DESKTOP-XXXX:~$
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Verify Docker is installed correctly:

docker --version
Enter fullscreen mode Exit fullscreen mode

Step 3 — Create Your Project Structure 

mkdir ~/projects/catalyst
cd ~/projects/catalyst
Enter fullscreen mode Exit fullscreen mode

Step 4 — Create the Dockerfile

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

nano Dockerfile
Enter fullscreen mode Exit fullscreen mode

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"]
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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 .
Enter fullscreen mode Exit fullscreen mode

Verify the image was created:

docker images
Enter fullscreen mode Exit fullscreen mode

You should see:

REPOSITORY     TAG       IMAGE ID       CREATED        SIZE
catalyst-cli   latest    xxxxxxxxxxxx   x hours ago    ...
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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/
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

root@your-machine:/app#
Enter fullscreen mode Exit fullscreen mode

Step 10 — Login to Zoho Catalyst 

catalyst login
Enter fullscreen mode Exit fullscreen mode
  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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

Troubleshooting

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.

Top comments (0)