Skip to main content

Local Development Setup Guide

Complete guide for setting up Orchestr8 on your local development machine.

Prerequisites​

System Requirements​

  • OS: Windows 10/11, macOS 10.15+, or Linux
  • Memory: 8GB RAM minimum, 16GB recommended
  • Storage: 20GB free space for containers and data
  • CPU: 2+ cores, 4+ cores recommended

CLI Tool Requirements​

Before deploying locally, ensure you have the required command-line tools. See the Prerequisites Guide for complete installation instructions for all tools.

Required for Local:

  • Core tools: kubectl, helm, git (required for all providers)
  • Local-specific: docker for container runtime (Docker Desktop or Docker Engine 20.10+)

Quick Verification:

# Verify all required tools are installed
o8 doctor --verbose

# Show installation instructions for missing tools
o8 doctor --fix

Platform Options​

Orchestr8 supports multiple local Kubernetes platforms:

  • Fast startup and lightweight
  • Excellent for development and CI
  • Good Docker Desktop alternative

2. Docker Desktop Kubernetes​

  • Easy setup on Windows/Mac
  • Integrated with Docker Desktop
  • Higher resource usage

3. minikube​

  • VM-based isolation
  • Feature-rich with addons
  • Good for testing different environments

4. k3s​

  • Minimal resource footprint
  • Production-grade lightweight K8s
  • Great for resource-constrained systems

Step 1: Install Orchestr8​

Install the Orchestr8 CLI using uv (ensure you have the prerequisites installed first):

# Install O8 CLI
uv tool install orchestr8-platform

# Verify installation
o8 --version

Step 2: Deploy Local Platform​

# Create local cluster and deploy platform
o8 setup --provider local

# This will:
# 1. Create a kind cluster (or use existing Docker Desktop)
# 2. Deploy ArgoCD, Istio, and Keycloak
# 3. Configure ingress and DNS
# 4. Set up GitOps workflow

Manual Setup Options​

Option 1: kind (Kubernetes in Docker)​

# Install kind
curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.20.0/kind-linux-amd64
chmod +x ./kind
sudo mv ./kind /usr/local/bin/kind

# Create cluster with custom config
cat <<EOF > kind-config.yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  kubeadmConfigPatches:
  - |
    kind: InitConfiguration
    nodeRegistration:
      kubeletExtraArgs:
        node-labels: "ingress-ready=true"
  extraPortMappings:
  - containerPort: 80
    hostPort: 80
    protocol: TCP
  - containerPort: 443
    hostPort: 443
    protocol: TCP
- role: worker
- role: worker
EOF

# Create cluster
kind create cluster --config kind-config.yaml --name orchestr8

# Deploy platform
o8 setup --provider local --existing-cluster orchestr8

Option 2: Docker Desktop Kubernetes​

# Enable Kubernetes in Docker Desktop settings
# Then deploy platform
o8 setup --provider local --existing-cluster docker-desktop

Option 3: minikube​

# Install minikube
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube

# Start cluster
minikube start --memory=8192 --cpus=4 --driver=docker

# Enable ingress addon
minikube addons enable ingress

# Deploy platform
o8 setup --provider local --existing-cluster minikube

Platform Configuration​

Local Domain Setup​

Orchestr8 uses local domains for development. Add these to your /etc/hosts (Linux/Mac) or C:\Windows\System32\drivers\etc\hosts (Windows):

127.0.0.1 argocd.local.orchestr8.io
127.0.0.1 keycloak.local.orchestr8.io
127.0.0.1 grafana.local.orchestr8.io
127.0.0.1 app.local.orchestr8.io

Port Forwarding (Alternative)​

If you prefer port-forwarding over ingress:

# ArgoCD
kubectl port-forward svc/argocd-server -n argocd 8080:80 &

# Keycloak
kubectl port-forward svc/keycloak -n keycloak 8090:80 &

# Grafana
kubectl port-forward svc/prometheus-grafana -n monitoring 3000:80 &

Development Workflow​

1. Access Services​

# Get service URLs
o8 status

# Sample output:
# ArgoCD: https://argocd.local.orchestr8.io
# Keycloak: https://keycloak.local.orchestr8.io
# Grafana: https://grafana.local.orchestr8.io

2. Deploy Applications​

# Create a sample application
o8 module init my-app --template nodejs

# Deploy to local environment
o8 module deploy my-app --environment local

3. Monitor and Debug​

# View module status
o8 module status my-app

# Check logs
kubectl logs -l app=my-app -n my-app

# Access application
curl http://my-app.local.orchestr8.io

Troubleshooting​

Common Issues​

Docker Desktop not starting​

# Windows: Reset Docker Desktop
# macOS: Restart Docker Desktop application
# Linux: Restart Docker service
sudo systemctl restart docker

kind cluster creation fails​

# Clean up and retry
kind delete cluster --name orchestr8
docker system prune -f
kind create cluster --name orchestr8

Port conflicts​

# Check what's using ports 80/443
# Windows:
netstat -ano | findstr :80
netstat -ano | findstr :443

# Linux/Mac:
lsof -i :80
lsof -i :443

# Use different ports if needed
kind create cluster --config kind-config-alt-ports.yaml

DNS resolution issues​

# Verify /etc/hosts entries
cat /etc/hosts | grep orchestr8

# Or use port-forwarding instead of ingress
o8 setup --provider local --use-port-forwarding

Performance Optimization​

Resource Limits​

# Check resource usage
kubectl top nodes
kubectl top pods --all-namespaces

# Adjust limits if needed
docker update --memory=12g --cpus=6 kind-control-plane

Storage Cleanup​

# Clean up unused Docker resources
docker system prune -a

# Clean up kind clusters
kind get clusters
kind delete cluster --name old-cluster

Advanced Configuration​

Custom Platform Values​

Create a local-values.yaml file:

# local-values.yaml
global:
  domain: local.orchestr8.io
  
argocd:
  configs:
    params:
      server.insecure: true
      
keycloak:
  auth:
    adminUser: admin
    adminPassword: admin123

istio:
  gateway:
    type: LoadBalancer  # or NodePort for some platforms

Deploy with custom values:

o8 setup --provider local --values local-values.yaml

Development Features​

Hot Reload​

# Enable hot reload for development
o8 module deploy my-app --environment local --hot-reload

Debug Mode​

# Deploy with debug symbols and tools
o8 module deploy my-app --environment local --debug

Cleanup​

Remove Platform​

# Remove Orchestr8 platform (keep cluster)
o8 destroy --keep-cluster

# Remove everything including cluster
o8 destroy --cluster orchestr8

Reset Environment​

# Complete cleanup
kind delete cluster --name orchestr8
docker system prune -a
rm -rf ~/.kube/config
rm -rf ~/.o8/

Next Steps​

  1. Deploy your first module: Follow the Module Development Guide
  2. Set up GitOps: Configure Git repository integration
  3. Monitor applications: Use Grafana dashboards
  4. Scale to cloud: Migrate to AWS/Azure/GCP when ready