# OrbStack Machine Setup Guide\n\n**Version**: 1.0.0\n**Last Updated**: 2025-10-06\n\nThis guide walks through setting up an OrbStack machine named "provisioning" for integration testing.\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [Prerequisites](#prerequisites)\n3. [Installing OrbStack](#installing-orbstack)\n4. [Creating the Provisioning Machine](#creating-the-provisioning-machine)\n5. [Configuring Resources](#configuring-resources)\n6. [Installing Prerequisites](#installing-prerequisites)\n7. [Deploying Platform for Testing](#deploying-platform-for-testing)\n8. [Verifying Setup](#verifying-setup)\n9. [Troubleshooting](#troubleshooting)\n\n---\n\n## Overview\n\nOrbStack is a lightweight, fast Docker and Linux environment for macOS. We use it to run integration tests in an isolated environment without \naffecting the host system.\n\n**Why OrbStack?**\n\n- ✅ **Fast**: Boots in seconds, much faster than traditional VMs\n- ✅ **Lightweight**: Uses minimal resources\n- ✅ **Native macOS Integration**: Seamless file sharing and networking\n- ✅ **Docker Compatible**: Full Docker API compatibility\n- ✅ **Easy Management**: Simple CLI for machine management\n\n---\n\n## Prerequisites\n\n- **macOS 12.0+** (Monterey or later)\n- **Homebrew** package manager\n- **4 GB+ RAM** available for OrbStack machine\n- **50 GB+ disk space** for containers and images\n\n---\n\n## Installing OrbStack\n\n### Option 1: Homebrew (Recommended)\n\n```\n# Install OrbStack via Homebrew\nbrew install --cask orbstack\n```\n\n### Option 2: Direct Download\n\n1. Download OrbStack from <https://orbstack.dev/download>\n2. Open the downloaded DMG file\n3. Drag OrbStack to Applications folder\n4. Launch OrbStack from Applications\n\n### Verify Installation\n\n```\n# Check OrbStack CLI is available\norb version\n\n# Expected output:\n# OrbStack 1.x.x\n```\n\n---\n\n## Creating the Provisioning Machine\n\n### Create Machine\n\n```\n# Create machine named "provisioning"\norb create provisioning\n\n# Output:\n# Creating machine "provisioning"...\n# Machine "provisioning" created successfully\n```\n\n### Start Machine\n\n```\n# Start the machine\norb start provisioning\n\n# Verify machine is running\norb status provisioning\n\n# Output:\n# Machine: provisioning\n# State: running\n# CPU: 4 cores\n# Memory: 8192 MB\n# Disk: 100 GB\n```\n\n### List All Machines\n\n```\n# List all OrbStack machines\norb list\n\n# Output (JSON):\n# [\n# {\n# "name": "provisioning",\n# "state": "running",\n# "cpu_cores": 4,\n# "memory_mb": 8192,\n# "disk_gb": 100\n# }\n# ]\n```\n\n---\n\n## Configuring Resources\n\n### Set CPU Cores\n\n```\n# Set CPU cores to 4\norb config provisioning --cpu 4\n```\n\n### Set Memory\n\n```\n# Set memory to 8 GB (8192 MB)\norb config provisioning --memory 8192\n```\n\n### Set Disk Size\n\n```\n# Set disk size to 100 GB\norb config provisioning --disk 100\n```\n\n### Apply All Settings at Once\n\n```\n# Configure all resources during creation\norb create provisioning --cpu 4 --memory 8192 --disk 100\n```\n\n### Recommended Resources\n\n| Component | Minimum | Recommended |\n| ----------- | --------- | ------------- |\n| CPU Cores | 2 | 4 |\n| Memory | 4 GB | 8 GB |\n| Disk | 50 GB | 100 GB |\n\n**Note**: Enterprise mode tests require more resources due to additional services (Harbor, ELK, etc.)\n\n---\n\n## Installing Prerequisites\n\n### Install Docker CLI\n\nOrbStack includes Docker, but you may need the Docker CLI:\n\n```\n# Install Docker CLI via Homebrew\nbrew install docker\n\n# Verify Docker is available\ndocker version\n```\n\n### Install Nushell\n\n```\n# Install Nushell\nbrew install nushell\n\n# Verify Nushell is installed\nnu --version\n\n# Expected: 0.107.1 or later\n```\n\n### Install Additional Tools\n\n```\n# Install dig for DNS testing\nbrew install bind\n\n# Install psql for PostgreSQL testing\nbrew install postgresql@15\n\n# Install git for Gitea testing\nbrew install git\n```\n\n---\n\n## Deploying Platform for Testing\n\n### Deploy Solo Mode\n\n```\n# Navigate to project directory\ncd /Us
