9.6 KiB
9.6 KiB
\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\nNote: 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\nDeployed 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\nDeployed 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\nDeployed 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\nDeployed 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\nSymptom: orb start provisioning fails\n\nSolutions:\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\nSymptom: docker -H /var/run/docker.sock ps fails\n\nSolutions:\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\nSymptom: Cannot connect to services\n\nSolutions:\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\nSymptom: Services fail to start due to lack of resources\n\nSolutions:\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\nSymptom: Container exits immediately after start\n\nSolutions:\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\n- OrbStack GitHub\n- Docker Documentation\n- Integration Testing Guide\n\n---\n\nMaintained By: Platform Team\nLast Updated: 2025-10-06