o8 setup

Set up a new Orchestr8 instance on any supported cloud provider or locally.

Synopsis

o8 setup [OPTIONS]

Description

The setup command initializes and deploys the complete Orchestr8 platform including:

• ArgoCD - GitOps continuous delivery engine
• Istio - Service mesh for traffic management and mTLS
• Keycloak - Identity and Access Management (IAM)
• OAuth2 Proxy - Service authentication layer
• Prometheus/Grafana - Monitoring and observability stack
• Cert-Manager - Automatic TLS certificate management

Depending on the provider, it can also provision cloud infrastructure automatically.

Options

Core Options

Option	Short	Description	Default
--provider	-p	Cloud provider (local, aws, gcp, azure)	local
--cluster	-c	Kubernetes cluster name	o8-cluster
--domain	-d	Platform domain (e.g., platform.example.com)	Required
--github-org	-g	GitHub organization	Required
--region	-r	Cloud region (for AWS/GCP/Azure)	us-east-1
--environment	-e	Environment (dev, staging, production)	dev

Authentication Options

Option	Short	Description	Default
--github-token		GitHub personal access token	From GITHUB_TOKEN env var
--auth-interactive	-a	Use interactive OAuth authentication	false
--non-interactive	-n	Run without prompts	false

Infrastructure Options

Option	Short	Description	Default
--provision-infrastructure	-i	Provision cloud infrastructure with Terraform	false
--gcp-project-id		GCP Project ID (required for GCP infrastructure provisioning)	None

Prerequisites

Core Requirements (All Providers)

• kubectl - Kubernetes management
• helm - Package management
• git - Version control

Provider-Specific Requirements

Local Provider

• docker - Container runtime (kind, minikube, Docker Desktop)

GCP Provider

• gcloud - GCP CLI and authentication
• terraform - For --provision-infrastructure flag

AWS Provider

• aws - AWS CLI and authentication
• Manual EKS cluster setup required (no automated provisioning yet)

Azure Provider

• az - Azure CLI and authentication
• Manual AKS cluster setup required (no automated provisioning yet)

Examples

Local Development

# Basic local setup
o8 setup --provider local

# Local setup with custom domain
o8 setup --provider local \
  --domain dev.example.com \
  --github-org mycompany

Google Cloud Platform

# Deploy to existing GKE cluster
o8 setup --provider gcp \
  --domain platform.example.com \
  --github-org mycompany \
  --gcp-project-id my-project-123

# Full GCP deployment with infrastructure provisioning
o8 setup --provider gcp \
  --provision-infrastructure \
  --gcp-project-id my-project-123 \
  --domain platform.example.com \
  --github-org mycompany \
  --region us-central1 \
  --environment production

Amazon Web Services

# Deploy to existing EKS cluster  
o8 setup --provider aws \
  --domain platform.example.com \
  --github-org mycompany \
  --region us-east-1

# Non-interactive deployment (CI/CD)
o8 setup --provider aws \
  --domain platform.example.com \
  --github-org mycompany \
  --github-token $GITHUB_TOKEN \
  --region us-east-1 \
  --non-interactive

Microsoft Azure

# Deploy to existing AKS cluster
o8 setup --provider azure \
  --domain platform.example.com \
  --github-org mycompany \
  --region eastus

Interactive Mode

When run without --non-interactive, the command will prompt for required information:

o8 setup --provider gcp

This will prompt for:

• Platform domain
• GitHub organization
• Authentication method (OAuth Device Flow or Personal Access Token)
• GCP Project ID (if using infrastructure provisioning)

Authentication Flow

GitHub Authentication

The setup process requires GitHub authentication for ArgoCD to access your repositories:

Option 1: OAuth Device Flow (Recommended)

• Secure browser-based authentication
• Requires GitHub OAuth App with device flow enabled
• Provides scoped access tokens

Option 2: Personal Access Token

• Manual token creation and entry
• Requires 'repo' scope for private repositories
• Less secure but works in headless environments

Cloud Provider Authentication

Ensure you're authenticated with your cloud provider before running setup:

# GCP
gcloud auth login
gcloud auth application-default login

# AWS  
aws configure
# or set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY

# Azure
az login

Infrastructure Provisioning

GCP (Full Support)

When using --provision-infrastructure with GCP, Terraform will create:

• GKE cluster with auto-scaling node groups
• VPC network and subnets
• Service accounts with Workload Identity
• Cloud NAT for private nodes
• Cloud DNS configuration (optional)

AWS/Azure (Manual Setup Required)

Currently requires manual cluster setup:

1. Create EKS/AKS cluster
2. Configure kubectl context
3. Run o8 setup without --provision-infrastructure

Output

Local Deployment

🎯 Access your platform:
   ArgoCD:      http://localhost:30080  (GitOps Dashboard)
   Keycloak:    http://localhost:30081  (Identity Management)  
   Platform:    http://localhost:30082  (OAuth2 Entry Point)

📱 Module UIs (behind Keycloak auth):
   VoiceFuse:   http://localhost:30083
   Langfuse:    http://localhost:30084

Cloud Deployment

Access Information:
ArgoCD URL:       https://argocd.platform.example.com
Keycloak URL:     https://keycloak.platform.example.com
ArgoCD Password:  [generated-password]

📌 Next steps:
1. Configure DNS for your domain
2. Access ArgoCD to monitor deployments  
3. Set up GitHub/Google OAuth in Keycloak (optional)

Configuration Storage

Setup creates configuration files in:

• ~/.orchestr8/config.yaml - Platform configuration
• ~/.orchestr8/terraform/ - Terraform state (if using infrastructure provisioning)
• ~/.kube/config - Kubernetes context (updated)

Troubleshooting

Common Issues

Authentication Errors

# Verify cloud provider authentication
o8 doctor

# Check GitHub token permissions
curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user

Infrastructure Provisioning Failures

# Check Terraform logs  
cd ~/.orchestr8/terraform/modules/bootstrap
terraform plan

# Verify GCP APIs are enabled
gcloud services enable container.googleapis.com
gcloud services enable compute.googleapis.com

Kubernetes Connection Issues

# Verify kubectl context
kubectl config current-context
kubectl cluster-info

# Check cluster access
kubectl get nodes

Retry After Fixes

The setup command is idempotent and can be safely re-run:

# Re-run setup after fixing issues
o8 setup --provider gcp --provision-infrastructure --gcp-project-id my-project

Exit Codes

Code	Description
0	Setup completed successfully
1	General setup failure
2	Configuration error (missing required options)
3	Authentication error (GitHub, cloud provider)
4	Infrastructure provisioning error

Related Commands

• o8 status - Check platform status after setup
• o8 doctor - Diagnose environment issues
• o8 teardown - Remove platform components
• o8 bootstrap create - Advanced cluster creation