Knowledge Hub

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