Skip to main content

Installation Guide

Complete setup instructions for deploying Orchestr8 on your chosen platform.

Step 1: Install Prerequisites​

Required tools:

Cloud-specific (if deploying to cloud):

Advanced/Optional Tools (Click to expand)

Development & Debugging:

  • helm - Kubernetes package manager (auto-installed by Orchestr8)
  • terraform - Infrastructure provisioning (only for --provision-infrastructure)
  • k9s - Kubernetes UI: k9scli.io
  • stern - Multi-pod logs: github.com/stern/stern

Cloud Development:

  • eksctl - EKS management (AWS): eksctl.io
  • kubelogin - AKS auth plugin (Azure)
  • gke-gcloud-auth-plugin - GKE auth (GCP)

Most tools are auto-installed or managed by Orchestr8. Install only what you need.

Step 2: Install Orchestr8 CLI​

Install the Orchestr8 CLI using uv:

# Install Orchestr8 CLI
uv tool install orchestr8-platform

# Verify installation
o8 --version

Step 3: Prepare GitOps Repository​

Orchestr8 uses GitOps principles, storing all configuration in Git repositories. Before deploying, you need to decide on your repository strategy:

Option 1: Use the Default Repository (Easiest)​

The CLI will use https://github.com/killerapp/orchestr8 by default. This works for getting started quickly.

Create a private repository in your GitHub organization to store your platform configuration:

  1. Create a new repository: https://github.com/YOUR-ORG/your-platform-config
  2. Initialize with the Orchestr8 template: The CLI can optionally fork/template from the main repository
  3. This repository will contain:
    • ArgoCD Application definitions
    • Environment-specific configurations
    • Module deployment manifests
    • GitOps workflow templates

Repository Setup Options:

  • Fork the main repo: gh repo fork killerapp/orchestr8 --clone
  • Template approach: Use as template and customize
  • Empty repo: Let Orchestr8 initialize the structure during setup

Why GitHub Authentication is Required​

During setup, you'll be prompted for GitHub authentication because:

  • ArgoCD needs access to your GitOps repository to sync configurations
  • Orchestr8 stores all configuration in Git (following GitOps best practices)
  • No secrets are stored in the cluster - everything comes from your repository

Step 4: Deploy Platform​

Local Development​

Perfect for learning, development, and testing:

# Deploy to local Kubernetes - you'll be prompted for GitHub org/auth
o8 setup --provider local --domain local.dev

# Or specify your GitHub organization upfront
o8 setup --provider local --domain local.dev --github-org YOUR-ORG

During setup, you'll see:

GitHub organization: YOUR-ORG
Checking repository: https://github.com/YOUR-ORG/orchestr8

⚠️  GitHub authentication is required
ArgoCD needs access to the orchestr8 repository

Authentication options:
  1. OAuth Device Flow (recommended - secure & easy)
  2. Personal Access Token (manual setup)

Cloud Deployment​

For production workloads with enterprise features:

AWS (Amazon EKS)​

# Deploy to existing EKS cluster
o8 setup --provider aws --domain your-domain.com

# Or provision new infrastructure with Terraform
o8 setup --provider aws --provision-infrastructure --domain your-domain.com

Azure (Azure AKS)​

# Deploy to existing AKS cluster  
o8 setup --provider azure --domain your-domain.com

Google Cloud (GKE)​

# Deploy to existing GKE cluster
o8 setup --provider gcp --domain your-domain.com

# Or provision new infrastructure
o8 setup --provider gcp --provision-infrastructure --gcp-project-id YOUR_PROJECT

Step 5: Verify Installation​

# Check all prerequisites and platform health
o8 doctor

# Check platform status
o8 status

Step 6: Deploy Your First Application​

Try deploying a sample module to verify everything works:

# Initialize a new module
o8 module init hello-world --template basic

# Deploy to development environment
o8 module deploy ./hello-world --environment dev

# Check deployment status
o8 module status hello-world

Advanced Configuration​

Authentication Setup​

Configure GitHub access for GitOps:

# Set up GitHub authentication
o8 auth --github-org your-org --github-token YOUR_TOKEN

# Configure ArgoCD repositories
o8 repos add-github your-org/your-config-repo

Identity Providers​

Configure external identity providers:

# GitHub OAuth
o8 idp github --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET

# Google OAuth  
o8 idp google --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET

# Microsoft Azure AD
o8 idp microsoft --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET

Multi-Tenancy​

For enterprise multi-tenant deployments:

# Initialize tenant
o8 tenant init customer-a --modules langfuse,voicefuse

# Deploy tenant to production
o8 tenant deploy customer-a --environment production

Troubleshooting​

Common fixes:

  • Missing tools: Run o8 doctor --fix to see installation instructions
  • Cloud auth: Run aws configure, az login, or gcloud auth login
  • Docker issues: Start Docker Desktop or Docker service

Get help: Run o8 doctor --verbose or check GitHub Issues

Next Steps​

  1. Explore Core Concepts - Understand GitOps and architecture
  2. Deploy Modules - Try example applications
  3. Configure Security - Harden your deployment