# 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](#overview)
2. [Prerequisites](#prerequisites)
3. [Installing OrbStack](#installing-orbstack)
4. [Creating the Provisioning Machine](#creating-the-provisioning-machine)
5. [Configuring Resources](#configuring-resources)
6. [Installing Prerequisites](#installing-prerequisites)
7. [Deploying Platform for Testing](#deploying-platform-for-testing)
8. [Verifying Setup](#verifying-setup)
9. [Troubleshooting](#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)

```bash
# 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

```bash
# Check OrbStack CLI is available
orb version

# Expected output:
# OrbStack 1.x.x
```

---

## Creating the Provisioning Machine

### Create Machine

```bash
# Create machine named "provisioning"
orb create provisioning

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

### Start Machine

```bash
# 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

```bash
# 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

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

### Set Memory

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

### Set Disk Size

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

### Apply All Settings at Once

```bash
# 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:

```bash
# Install Docker CLI via Homebrew
brew install docker

# Verify Docker is available
docker version
```

### Install Nushell

```bash
# Install Nushell
brew install nushell

# Verify Nushell is installed
nu --version

# Expected: 0.107.1 or later
```

### Install Additional Tools

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Check machine status
orb status provisioning

# Expected: state = "running"
```

### Verify Docker Connectivity

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

# Expected: List of running containers
```

### Verify Services are Healthy

```bash
# 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

```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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`:

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

### Persistent Volumes

```bash
# 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

```bash
# 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

```bash
# Stop machine (preserves data)
orb stop provisioning
```

### Delete Machine

```bash
# Delete machine (removes all data)
orb delete provisioning

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

### Cleanup Docker Resources

```bash
# 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](https://orbstack.dev/docs)
- [OrbStack GitHub](https://github.com/orbstack/orbstack)
- [Docker Documentation](https://docs.docker.com)
- [Integration Testing Guide](TESTING_GUIDE.md)

---

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