provisioning/tests/integration/docs/ORBSTACK_SETUP.md

OrbStack Machine Setup Guide

Version: 1.0.0 Last Updated: 2025-10-06

This guide walks through setting up an OrbStack machine named "provisioning" for integration testing.

Table of Contents

1. Overview
2. Prerequisites
3. Installing OrbStack
4. Creating the Provisioning Machine
5. Configuring Resources
6. Installing Prerequisites
7. Deploying Platform for Testing
8. Verifying Setup
9. Troubleshooting

---

Overview

OrbStack is a lightweight, fast Docker and Linux environment for macOS. We use it to run integration tests in an isolated environment without affecting the host system.

Why OrbStack?

• ✅ Fast: Boots in seconds, much faster than traditional VMs
• ✅ Lightweight: Uses minimal resources
• ✅ Native macOS Integration: Seamless file sharing and networking
• ✅ Docker Compatible: Full Docker API compatibility
• ✅ Easy Management: Simple CLI for machine management

---

Prerequisites

• macOS 12.0+ (Monterey or later)
• Homebrew package manager
• 4 GB+ RAM available for OrbStack machine
• 50 GB+ disk space for containers and images

---

Installing OrbStack

Option 1: Homebrew (Recommended)

# Install OrbStack via Homebrew
brew install --cask orbstack

Option 2: Direct Download

1. Download OrbStack from https://orbstack.dev/download
2. Open the downloaded DMG file
3. Drag OrbStack to Applications folder
4. Launch OrbStack from Applications

Verify Installation

# Check OrbStack CLI is available
orb version

# Expected output:
# OrbStack 1.x.x

---

Creating the Provisioning Machine

Create Machine

# Create machine named "provisioning"
orb create provisioning

# Output:
# Creating machine "provisioning"...
# Machine "provisioning" created successfully

Start Machine

# Start the machine
orb start provisioning

# Verify machine is running
orb status provisioning

# Output:
# Machine: provisioning
# State: running
# CPU: 4 cores
# Memory: 8192 MB
# Disk: 100 GB

List All Machines

# List all OrbStack machines
orb list

# Output (JSON):
# [
#   {
#     "name": "provisioning",
#     "state": "running",
#     "cpu_cores": 4,
#     "memory_mb": 8192,
#     "disk_gb": 100
#   }
# ]

---

Configuring Resources

Set CPU Cores

# Set CPU cores to 4
orb config provisioning --cpu 4

Set Memory

# Set memory to 8 GB (8192 MB)
orb config provisioning --memory 8192

Set Disk Size

# Set disk size to 100 GB
orb config provisioning --disk 100

Apply All Settings at Once

# Configure all resources during creation
orb create provisioning --cpu 4 --memory 8192 --disk 100

Recommended Resources

Component	Minimum	Recommended
CPU Cores	2	4
Memory	4 GB	8 GB
Disk	50 GB	100 GB

Note: Enterprise mode tests require more resources due to additional services (Harbor, ELK, etc.)

---

Installing Prerequisites

Install Docker CLI

OrbStack includes Docker, but you may need the Docker CLI:

# Install Docker CLI via Homebrew
brew install docker

# Verify Docker is available
docker version

Install Nushell

# Install Nushell
brew install nushell

# Verify Nushell is installed
nu --version

# Expected: 0.107.1 or later

Install Additional Tools

# Install dig for DNS testing
brew install bind

# Install psql for PostgreSQL testing
brew install postgresql@15

# Install git for Gitea testing
brew install git

---

Deploying Platform for Testing

Deploy Solo Mode

# Navigate to project directory
cd /Users/Akasha/project-provisioning

# Deploy solo mode to OrbStack
nu provisioning/tests/integration/setup_test_environment.nu --mode solo

Deployed Services:

• Orchestrator (172.20.0.10:8080)
• CoreDNS (172.20.0.2:53)
• Zot OCI Registry (172.20.0.20:5000)

Deploy Multi-User Mode

# Deploy multi-user mode
nu provisioning/tests/integration/setup_test_environment.nu --mode multiuser

Deployed Services:

• Solo mode services +
• Gitea (172.20.0.30:3000)
• PostgreSQL (172.20.0.40:5432)

Deploy CI/CD Mode

# Deploy CI/CD mode
nu provisioning/tests/integration/setup_test_environment.nu --mode cicd

Deployed Services:

• Multi-user mode services +
• API Server (enabled in orchestrator)
• Prometheus (172.20.0.50:9090)

Deploy Enterprise Mode

# Deploy enterprise mode
nu provisioning/tests/integration/setup_test_environment.nu --mode enterprise

Deployed Services:

• CI/CD mode services +
• Harbor OCI Registry (172.20.0.21:443)
• Grafana (172.20.0.51:3000)
• KMS (integrated with orchestrator)
• Elasticsearch (for audit logging)

---

Verifying Setup

Verify Machine is Running

# Check machine status
orb status provisioning

# Expected: state = "running"

Verify Docker Connectivity

# List running containers
docker -H /var/run/docker.sock ps

# Expected: List of running containers

Verify Services are Healthy

# Check orchestrator health
curl http://172.20.0.10:8080/health

# Expected: {"status": "healthy"}

# Check CoreDNS
dig @172.20.0.2 test.local

# Expected: DNS query response

# Check OCI registry
curl http://172.20.0.20:5000/v2/

# Expected: {}

Run Smoke Test

# Run a simple smoke test
nu provisioning/tests/integration/framework/test_runner.nu --filter "health" --mode solo

# Expected: All health check tests pass

---

Troubleshooting

Machine Won't Start

Symptom: orb start provisioning fails

Solutions:

# Check OrbStack daemon
ps aux | grep orbstack

# Restart OrbStack app
killall OrbStack
open -a OrbStack

# Recreate machine
orb delete provisioning
orb create provisioning

Docker Connection Failed

Symptom: docker -H /var/run/docker.sock ps fails

Solutions:

# Verify Docker socket exists
ls -la /var/run/docker.sock

# Check OrbStack is running
orb status provisioning

# Restart machine
orb restart provisioning

Network Connectivity Issues

Symptom: Cannot connect to services

Solutions:

# Check Docker network
docker -H /var/run/docker.sock network ls

# Recreate provisioning network
docker -H /var/run/docker.sock network rm provisioning-net
nu provisioning/tests/integration/framework/orbstack_helpers.nu orbstack-create-network

# Verify network exists
docker -H /var/run/docker.sock network inspect provisioning-net

Resource Exhaustion

Symptom: Services fail to start due to lack of resources

Solutions:

# Increase machine resources
orb config provisioning --cpu 8 --memory 16384

# Restart machine
orb restart provisioning

# Check resource usage
docker -H /var/run/docker.sock stats

Service Container Crashes

Symptom: Container exits immediately after start

Solutions:

# Check container logs
docker -H /var/run/docker.sock logs <container_name>

# Check container exit code
docker -H /var/run/docker.sock inspect <container_name> | grep ExitCode

# Restart container
docker -H /var/run/docker.sock restart <container_name>

---

Advanced Configuration

Custom Network Subnet

Edit provisioning/tests/integration/test_config.yaml:

orbstack:
  network:
    subnet: "172.30.0.0/16"  # Custom subnet
    gateway: "172.30.0.1"
    dns: ["172.30.0.2"]

Persistent Volumes

# Create named volume for data persistence
docker -H /var/run/docker.sock volume create provisioning-data

# Mount volume in container
docker -H /var/run/docker.sock run -v provisioning-data:/data ...

SSH Access to Machine

# SSH into OrbStack machine
orb ssh provisioning

# Now you're inside the machine
# Install additional tools if needed
apt-get update && apt-get install -y vim curl

---

Cleanup

Stop Machine

# Stop machine (preserves data)
orb stop provisioning

Delete Machine

# Delete machine (removes all data)
orb delete provisioning

# Confirm deletion
# This will remove all containers, volumes, and data

Cleanup Docker Resources

# Remove all containers
docker -H /var/run/docker.sock rm -f $(docker -H /var/run/docker.sock ps -aq)

# Remove all volumes
docker -H /var/run/docker.sock volume prune -f

# Remove all networks
docker -H /var/run/docker.sock network prune -f

---

Best Practices

1. Regular Cleanup: Clean up unused containers and volumes regularly
2. Resource Monitoring: Monitor resource usage to prevent exhaustion
3. Automated Setup: Use setup scripts for consistent environments
4. Version Control: Track OrbStack machine configuration in version control
5. Backup Important Data: Backup test data before major changes

---

References

• OrbStack Official Documentation
• OrbStack GitHub
• Docker Documentation
• Integration Testing Guide

---

Maintained By: Platform Team Last Updated: 2025-10-06