Prerequisites

Before installing and using OpenFrame CLI, ensure your system meets the following requirements and has the necessary dependencies installed.

System Requirements

Hardware Requirements

Operating System Support

Windows Users: OpenFrame CLI requires WSL2 for proper Kubernetes integration. Native Windows support is not currently available.

Required Dependencies

Core Dependencies

These tools must be installed before using OpenFrame CLI:

Development Dependencies (Optional)

Required only if using development features (openframe dev commands):

Installation Verification

Check Docker

docker --version
docker ps

Expected output:

Docker version 20.10.0 or higher
CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS   PORTS   NAMES

Check kubectl

kubectl version --client

Expected output:

Client Version: version.Info{Major:"1", Minor:"25"+...}

Check Helm

helm version

Expected output:

version.BuildInfo{Version:"v3.10.0"+...}

Check K3D

k3d version

Expected output:

k3d version v5.0.0+

Check Telepresence (Optional)

telepresence version

Expected output:

Client: v2.10.0+

Check jq (Optional)

jq --version

Expected output:

jq-1.6+

Network Requirements

Outbound Connectivity

OpenFrame CLI requires internet access for:

• Pulling Docker images
• Downloading Helm charts
• Accessing Git repositories
• Installing prerequisites

Port Requirements

Firewall Considerations

Ensure your firewall allows:

• Docker daemon communication
• Kubernetes cluster communication
• Outbound HTTPS connections

Environment Variables

Set these environment variables for optimal experience:

Required

# Docker daemon configuration
export DOCKER_HOST="unix:///var/run/docker.sock"

# Kubernetes configuration
export KUBECONFIG="$HOME/.kube/config"

Optional

# OpenFrame CLI configuration
export OPENFRAME_LOG_LEVEL="info"
export OPENFRAME_CONFIG_DIR="$HOME/.openframe"

# Development tools
export TELEPRESENCE_LOGIN_DOMAIN="auth.datawire.io"

Account Requirements

Container Registry Access

• Public registries: Docker Hub, GHCR.io (no authentication required)
• Private registries: Configure Docker credentials if using private images

Git Repository Access

• Public repositories: No authentication required
• Private repositories: Configure SSH keys or personal access tokens

Quick Setup Script

For convenience, here's a script to verify all prerequisites:

#!/bin/bash
# prerequisites-check.sh

echo "🔍 Checking OpenFrame CLI prerequisites..."

# Function to check if command exists
command_exists() {
    command -v "$1" >/dev/null 2>&1
}

# Function to check version
check_version() {
    local tool="$1"
    local min_version="$2"
    local current_version="$3"
    
    echo "  $tool: $current_version (required: $min_version+)"
}

errors=0

# Check Docker
if command_exists docker; then
    docker_version=$(docker --version | cut -d' ' -f3 | cut -d',' -f1)
    check_version "Docker" "20.10.0" "$docker_version"
    if ! docker ps >/dev/null 2>&1; then
        echo "  ❌ Docker daemon is not running or accessible"
        ((errors++))
    fi
else
    echo "  ❌ Docker not found"
    ((errors++))
fi

# Check kubectl
if command_exists kubectl; then
    kubectl_version=$(kubectl version --client -o json 2>/dev/null | jq -r '.clientVersion.gitVersion' 2>/dev/null || echo "unknown")
    check_version "kubectl" "1.25.0" "$kubectl_version"
else
    echo "  ❌ kubectl not found"
    ((errors++))
fi

# Check Helm
if command_exists helm; then
    helm_version=$(helm version --short | cut -d'+' -f1)
    check_version "Helm" "3.10.0" "$helm_version"
else
    echo "  ❌ Helm not found"
    ((errors++))
fi

# Check K3D
if command_exists k3d; then
    k3d_version=$(k3d version | grep k3d | cut -d' ' -f2)
    check_version "K3D" "5.0.0" "$k3d_version"
else
    echo "  ❌ K3D not found"
    ((errors++))
fi

# Check optional tools
echo ""
echo "📋 Optional development tools:"

if command_exists telepresence; then
    telepresence_version=$(telepresence version --output=json 2>/dev/null | jq -r '.client.version' 2>/dev/null || "unknown")
    check_version "Telepresence" "2.10.0" "$telepresence_version"
else
    echo "  ⚠️  Telepresence not found (optional for dev workflows)"
fi

if command_exists jq; then
    jq_version=$(jq --version | cut -d'-' -f2)
    check_version "jq" "1.6" "$jq_version"
else
    echo "  ⚠️  jq not found (optional for dev scripts)"
fi

echo ""
if [ $errors -eq 0 ]; then
    echo "✅ All required prerequisites are installed!"
    echo "🚀 You're ready to install OpenFrame CLI"
else
    echo "❌ $errors required dependencies are missing"
    echo "📖 Please install missing dependencies before proceeding"
    exit 1
fi

Save this as prerequisites-check.sh, make it executable, and run:

chmod +x prerequisites-check.sh
./prerequisites-check.sh

Troubleshooting Common Issues

Docker Permission Issues

If you get permission denied errors:

# Add your user to the docker group
sudo usermod -aG docker $USER

# Log out and back in, or run:
newgrp docker

kubectl Not Finding Config

# Create kubeconfig directory
mkdir -p ~/.kube

# Verify KUBECONFIG environment variable
echo `$KUBECONFIG`

K3D Installation Issues on macOS

# If using Homebrew
brew install k3d

# If using curl
curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash

WSL2 Setup on Windows

1. Enable WSL2: wsl --install
2. Install Ubuntu from Microsoft Store
3. Install Docker Desktop with WSL2 backend
4. Install all prerequisites inside WSL2 environment

Next Steps

Once all prerequisites are installed and verified:

1. Quick Start Guide - Install OpenFrame CLI and bootstrap your first environment
2. First Steps Guide - Explore key features and workflows

Need help? Join our community:

• OpenMSP Slack: Join here