# 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 /Users/Akasha/project-provisioning\n\n# Deploy solo mode to OrbStack\nnu provisioning/tests/integration/setup_test_environment.nu --mode solo\n```\n\n**Deployed Services**:\n\n- Orchestrator (172.20.0.10:9090)\n- CoreDNS (172.20.0.2:53)\n- Zot OCI Registry (172.20.0.20:5000)\n\n### Deploy Multi-User Mode\n\n```\n# Deploy multi-user mode\nnu provisioning/tests/integration/setup_test_environment.nu --mode multiuser\n```\n\n**Deployed Services**:\n\n- Solo mode services +\n- Gitea (172.20.0.30:3000)\n- PostgreSQL (172.20.0.40:5432)\n\n### Deploy CI/CD Mode\n\n```\n# Deploy CI/CD mode\nnu provisioning/tests/integration/setup_test_environment.nu --mode cicd\n```\n\n**Deployed Services**:\n\n- Multi-user mode services +\n- API Server (enabled in orchestrator)\n- Prometheus (172.20.0.50:9090)\n\n### Deploy Enterprise Mode\n\n```\n# Deploy enterprise mode\nnu provisioning/tests/integration/setup_test_environment.nu --mode enterprise\n```\n\n**Deployed Services**:\n\n- CI/CD mode services +\n- Harbor OCI Registry (172.20.0.21:443)\n- Grafana (172.20.0.51:3000)\n- KMS (integrated with orchestrator)\n- Elasticsearch (for audit logging)\n\n---\n\n## Verifying Setup\n\n### Verify Machine is Running\n\n```\n# Check machine status\norb status provisioning\n\n# Expected: state = "running"\n```\n\n### Verify Docker Connectivity\n\n```\n# List running containers\ndocker -H /var/run/docker.sock ps\n\n# Expected: List of running containers\n```\n\n### Verify Services are Healthy\n\n```\n# Check orchestrator health\ncurl http://172.20.0.10:9090/health\n\n# Expected: {"status": "healthy"}\n\n# Check CoreDNS\ndig @172.20.0.2 test.local\n\n# Expected: DNS query response\n\n# Check OCI registry\ncurl http://172.20.0.20:5000/v2/\n\n# Expected: {}\n```\n\n### Run Smoke Test\n\n```\n# Run a simple smoke test\nnu provisioning/tests/integration/framework/test_runner.nu --filter "health" --mode solo\n\n# Expected: All health check tests pass\n```\n\n---\n\n## Troubleshooting\n\n### Machine Won't Start\n\n**Symptom**: `orb start provisioning` fails\n\n**Solutions**:\n\n```\n# Check OrbStack daemon\nps aux | grep orbstack\n\n# Restart OrbStack app\nkillall OrbStack\nopen -a OrbStack\n\n# Recreate machine\norb delete provisioning\norb create provisioning\n```\n\n### Docker Connection Failed\n\n**Symptom**: `docker -H /var/run/docker.sock ps` fails\n\n**Solutions**:\n\n```\n# Verify Docker socket exists\nls -la /var/run/docker.sock\n\n# Check OrbStack is running\norb status provisioning\n\n# Restart machine\norb restart provisioning\n```\n\n### Network Connectivity Issues\n\n**Symptom**: Cannot connect to services\n\n**Solutions**:\n\n```\n# Check Docker network\ndocker -H /var/run/docker.sock network ls\n\n# Recreate provisioning network\ndocker -H /var/run/docker.sock network rm provisioning-net\nnu provisioning/tests/integration/framework/orbstack_helpers.nu orbstack-create-network\n\n# Verify network exists\ndocker -H /var/run/docker.sock network inspect provisioning-net\n```\n\n### Resource Exhaustion\n\n**Symptom**: Services fail to start due to lack of resources\n\n**Solutions**:\n\n```\n# Increase machine resources\norb config provisioning --cpu 8 --memory 16384\n\n# Restart machine\norb restart provisioning\n\n# Check resource usage\ndocker -H /var/run/docker.sock stats\n```\n\n### Service Container Crashes\n\n**Symptom**: Container exits immediately after start\n\n**Solutions**:\n\n```\n# Check container logs\ndocker -H /var/run/docker.sock logs <container_name>\n\n# Check container exit code\ndocker -H /var/run/docker.sock inspect <container_name> | grep ExitCode\n\n# Restart container\ndocker -H /var/run/docker.sock restart <container_name>\n```\n\n---\n\n## Advanced Configuration\n\n### Custom Network Subnet\n\nEdit `provisioning/tests/integration/test_config.yaml`:\n\n```\norbstack:\n  network:\n    subnet: "172.30.0.0/16"  # Custom subnet\n    gateway: "172.30.0.1"\n    dns: ["172.30.0.2"]\n```\n\n### Persistent Volumes\n\n```\n# Create named volume for data persistence\ndocker -H /var/run/docker.sock volume create provisioning-data\n\n# Mount volume in container\ndocker -H /var/run/docker.sock run -v provisioning-data:/data ...\n```\n\n### SSH Access to Machine\n\n```\n# SSH into OrbStack machine\norb ssh provisioning\n\n# Now you're inside the machine\n# Install additional tools if needed\napt-get update && apt-get install -y vim curl\n```\n\n---\n\n## Cleanup\n\n### Stop Machine\n\n```\n# Stop machine (preserves data)\norb stop provisioning\n```\n\n### Delete Machine\n\n```\n# Delete machine (removes all data)\norb delete provisioning\n\n# Confirm deletion\n# This will remove all containers, volumes, and data\n```\n\n### Cleanup Docker Resources\n\n```\n# Remove all containers\ndocker -H /var/run/docker.sock rm -f $(docker -H /var/run/docker.sock ps -aq)\n\n# Remove all volumes\ndocker -H /var/run/docker.sock volume prune -f\n\n# Remove all networks\ndocker -H /var/run/docker.sock network prune -f\n```\n\n---\n\n## Best Practices\n\n1. **Regular Cleanup**: Clean up unused containers and volumes regularly\n2. **Resource Monitoring**: Monitor resource usage to prevent exhaustion\n3. **Automated Setup**: Use setup scripts for consistent environments\n4. **Version Control**: Track OrbStack machine configuration in version control\n5. **Backup Important Data**: Backup test data before major changes\n\n---\n\n## References\n\n- [OrbStack Official Documentation](https://orbstack.dev/docs)\n- [OrbStack GitHub](https://github.com/orbstack/orbstack)\n- [Docker Documentation](https://docs.docker.com)\n- [Integration Testing Guide](TESTING_GUIDE.md)\n\n---\n\n**Maintained By**: Platform Team\n**Last Updated**: 2025-10-06