9.3 KiB
9.3 KiB
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
- Overview
- Prerequisites
- Installing OrbStack
- Creating the Provisioning Machine
- Configuring Resources
- Installing Prerequisites
- Deploying Platform for Testing
- Verifying Setup
- 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
```text
### 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
```text
---
## Creating the Provisioning Machine
### Create Machine
```bash
# Create machine named "provisioning"
orb create provisioning
# Output:
# Creating machine "provisioning"...
# Machine "provisioning" created successfully
```text
### 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
```text
### 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
# }
# ]
```text
---
## Configuring Resources
### Set CPU Cores
```bash
# Set CPU cores to 4
orb config provisioning --cpu 4
```text
### Set Memory
```bash
# Set memory to 8 GB (8192 MB)
orb config provisioning --memory 8192
```text
### Set Disk Size
```bash
# Set disk size to 100 GB
orb config provisioning --disk 100
```text
### Apply All Settings at Once
```bash
# Configure all resources during creation
orb create provisioning --cpu 4 --memory 8192 --disk 100
```text
### 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
```text
### Install Nushell
```bash
# Install Nushell
brew install nushell
# Verify Nushell is installed
nu --version
# Expected: 0.107.1 or later
```text
### 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
```text
---
## 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
```text
**Deployed Services**:
- Orchestrator (172.20.0.10:9090)
- 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
```text
**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
```text
**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
```text
**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"
```text
### Verify Docker Connectivity
```bash
# List running containers
docker -H /var/run/docker.sock ps
# Expected: List of running containers
```text
### Verify Services are Healthy
```bash
# Check orchestrator health
curl http://172.20.0.10:9090/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: {}
```text
### 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
```text
---
## 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
```text
### 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
```text
### 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
```text
### 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
```text
### 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>
```text
---
## 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"]
```text
### 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 ...
```text
### 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
```text
---
## Cleanup
### Stop Machine
```bash
# Stop machine (preserves data)
orb stop provisioning
```text
### Delete Machine
```bash
# Delete machine (removes all data)
orb delete provisioning
# Confirm deletion
# This will remove all containers, volumes, and data
```text
### 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
```text
---
## 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