Installation Guide

Complete guide to installing and setting up Cluster Code on your system.

Table of Contents

  1. Prerequisites
    1. Required
    2. Optional (Based on Your Needs)
  2. Installation Methods
    1. Method 1: NPM Global Install (Recommended)
    2. Method 2: Install from Source
    3. Method 3: Run with npx (No Installation)
    4. Method 4: Local Project Dependency
  3. Post-Installation Setup
    1. 1. Verify Installation
    2. 2. Initialize Configuration
    3. 3. Verify kubectl Access
  4. Troubleshooting Installation Issues
    1. Command Not Found
    2. Permission Errors (Linux/macOS)
    3. Node.js Version Issues
    4. kubectl Not Found
    5. Installation Behind Corporate Proxy
    6. Offline Installation
  5. Platform-Specific Notes
    1. macOS
    2. Linux (Ubuntu/Debian)
    3. Linux (RHEL/CentOS/Fedora)
    4. Windows
    5. Docker Container
  6. Verifying Your Setup
  7. Upgrading Cluster Code
    1. Check for Updates
    2. Upgrade to Latest Version
    3. Downgrade to Specific Version
  8. Uninstalling Cluster Code
    1. Remove Global Installation
    2. Clean Uninstall
  9. Next Steps
  10. Getting Help

Prerequisites

Before installing Cluster Code, ensure you have the following installed:

Required

  • Node.js 18.0 or higher
  • npm 9.0 or higher
  • kubectl 1.28 or higher
  • Git (for repository operations)

Check your versions:

node --version  # Should be v18.0.0 or higher
npm --version   # Should be 9.0.0 or higher
kubectl version --client  # Should be v1.28.0 or higher

Optional (Based on Your Needs)

Install these tools based on which features you plan to use:

Tool Version Purpose Install Link
Azure CLI (az) 2.50+ Azure AKS/ARO management Install
AWS CLI (aws) 2.13+ AWS EKS management Install
gcloud CLI 400.0+ GCP GKE management Install
OpenShift CLI (oc) 4.15+ OpenShift features Install
Helm 3.12+ Helm deployments Install
ArgoCD CLI 2.8+ GitOps workflows Install
Ollama latest Local LLM support Install

Installation Methods

The easiest way to install Cluster Code is via npm:

# Install the package globally
npm install -g cluster-code

# Verify installation
cluster-code --version

Scoped package option:

# Install using scoped package name
npm install -g @cluster-code/cluster-code

Both cluster-code and @cluster-code/cluster-code install the same package. The unscoped version is an alias for convenience.

Method 2: Install from Source

For development or contributing:

# Clone the repository
git clone https://github.com/kcns008/cluster-code.git
cd cluster-code

# Install dependencies
npm install

# Build the project
npm run build

# Link for global use
npm link

# Verify installation
cluster-code --version

Method 3: Run with npx (No Installation)

Use Cluster Code without installing it globally:

# Run commands directly with npx
npx cluster-code diagnose

# Or using scoped package
npx @cluster-code/cluster-code diagnose

Using npx will download the package each time you run it. For regular use, we recommend global installation.

Method 4: Local Project Dependency

Add Cluster Code as a dependency in your Node.js project:

# Install as project dependency
npm install cluster-code

# Add to package.json scripts

package.json:

{
  "scripts": {
    "cluster:diagnose": "cluster-code diagnose",
    "cluster:status": "cluster-code status"
  },
  "dependencies": {
    "cluster-code": "^1.0.0"
  }
}

Post-Installation Setup

1. Verify Installation 

# Check version
cluster-code --version

# Check help
cluster-code --help

# List available commands
cluster-code list-commands

Expected output:

cluster-code version 1.0.0
✓ Node.js v20.10.0
✓ kubectl v1.28.0
✓ Configuration: ~/.cluster-code/config.json

2. Initialize Configuration

Create the default configuration file:

# Initialize with defaults
cluster-code config init

# Or use custom config location
cluster-code config init --config ~/.custom-cluster-code.json

This creates ~/.cluster-code/config.json with default settings.

3. Verify kubectl Access

Ensure you have access to a Kubernetes cluster:

# List available contexts
kubectl config get-contexts

# Set current context
kubectl config use-context <context-name>

# Verify cluster access
kubectl cluster-info

Troubleshooting Installation Issues

Command Not Found

If cluster-code command is not recognized after installation:

Linux/macOS:

# Check npm global bin directory
npm config get prefix

# Add to PATH
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For zsh users
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Windows:

# Check npm global bin directory
npm config get prefix

# Add to PATH via Environment Variables
# Windows: System Properties > Environment Variables > Path > Add npm prefix\bin

Permission Errors (Linux/macOS)

If you get EACCES errors during installation:

# Fix npm permissions (recommended)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Reinstall
npm install -g cluster-code

Avoid using sudo npm install -g as it can cause permission issues. Use the method above instead.

Node.js Version Issues

If you have an older Node.js version:

# Install nvm (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install Node.js 20 LTS
nvm install 20
nvm use 20

# Reinstall cluster-code
npm install -g cluster-code

kubectl Not Found

If kubectl is not installed:

Linux:

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

macOS:

brew install kubectl

Windows:

choco install kubernetes-cli

Installation Behind Corporate Proxy

Configure npm to use your proxy:

# Set proxy
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# Set registry (if using internal mirror)
npm config set registry https://registry.company.com/

# Install with proxy settings
npm install -g cluster-code

Offline Installation

For air-gapped environments:

# On a machine with internet access:
# Download the package
npm pack cluster-code

# This creates: cluster-code-1.0.0.tgz

# Transfer the .tgz file to your offline machine

# On offline machine:
npm install -g cluster-code-1.0.0.tgz

Platform-Specific Notes

macOS 

# Install via Homebrew (if available)
brew tap kcns008/cluster-code
brew install cluster-code

# Or use npm
npm install -g cluster-code

Linux (Ubuntu/Debian) 

# Install Node.js from NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install cluster-code
npm install -g cluster-code

Linux (RHEL/CentOS/Fedora) 

# Install Node.js from NodeSource
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs

# Install cluster-code
npm install -g cluster-code

Windows 

# Install via Chocolatey (recommended)
choco install nodejs
choco install kubernetes-cli

# Install cluster-code
npm install -g cluster-code

# Or use Windows Terminal with WSL2
wsl --install
# Then follow Linux instructions

Docker Container

Run Cluster Code in a container:

# Create Dockerfile
cat > Dockerfile <<EOF
FROM node:20-alpine

# Install kubectl
RUN apk add --no-cache curl && \
    curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl" && \
    install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl && \
    rm kubectl

# Install cluster-code
RUN npm install -g cluster-code

# Set working directory
WORKDIR /workspace

# Entry point
ENTRYPOINT ["cluster-code"]
EOF

# Build image
docker build -t cluster-code:latest .

# Run with kubectl config mounted
docker run -it --rm \
  -v ~/.kube:/root/.kube:ro \
  -v ~/.cluster-code:/root/.cluster-code \
  cluster-code:latest diagnose

Verifying Your Setup

Run this verification script to check your installation:

#!/bin/bash
echo "🔍 Verifying Cluster Code Installation"
echo "======================================="
echo ""

# Check Node.js
echo -n "✓ Node.js: "
node --version

# Check npm
echo -n "✓ npm: "
npm --version

# Check cluster-code
echo -n "✓ Cluster Code: "
cluster-code --version

# Check kubectl
echo -n "✓ kubectl: "
kubectl version --client --short 2>/dev/null || echo "⚠️  Not installed"

# Check optional tools
echo -n "✓ Azure CLI: "
az version --query '\"azure-cli\"' -o tsv 2>/dev/null || echo "⚠️  Not installed (optional)"

echo -n "✓ AWS CLI: "
aws --version 2>/dev/null | cut -d' ' -f1 || echo "⚠️  Not installed (optional)"

echo -n "✓ Helm: "
helm version --short 2>/dev/null || echo "⚠️  Not installed (optional)"

echo ""
echo "✅ Verification complete!"

Upgrading Cluster Code

Check for Updates 

# Check current version
cluster-code --version

# Check latest available version
npm view cluster-code version

# Or
npm outdated -g cluster-code

Upgrade to Latest Version 

# Upgrade via npm
npm update -g cluster-code

# Or reinstall
npm install -g cluster-code@latest

# Verify new version
cluster-code --version

Downgrade to Specific Version 

# Install specific version
npm install -g cluster-code@1.0.0

# Verify version
cluster-code --version

Uninstalling Cluster Code

Remove Global Installation 

# Uninstall via npm
npm uninstall -g cluster-code

# Remove configuration (optional)
rm -rf ~/.cluster-code

# Verify removal
cluster-code --version  # Should show command not found

Clean Uninstall 

# Remove everything
npm uninstall -g cluster-code
rm -rf ~/.cluster-code
rm -rf ~/.npm/_cacache/cluster-code

# Verify
which cluster-code  # Should return nothing

Next Steps

Now that Cluster Code is installed, continue with:

  1. LLM Provider Setup - Configure your AI provider
  2. Getting Started - First steps with Cluster Code
  3. Configuration Guide - Customize your setup

Or jump straight to:

Getting Help

If you encounter issues during installation: