OrbStack (Docker on Mac)

--- name: OrbStack (Docker on Mac) description: Use when working with Docker containers on macOS, especially for development environments requiring better performance than Docker Desktop metadata: author: skynet version: 1.0.0 category: infrastructure --- # OrbStack (Docker on Mac) ## Overview OrbStack is a fast, lightweight Docker Desktop alternative for macOS that provides better performance and resource usage for container development. ## Installation & Setup ### Install OrbStack ```bash # Download from https://orbstack.dev or use Homebrew brew install orbstack # Start OrbStack open /Applications/OrbStack.app ``` ### Migration from Docker Desktop ```bash # Export existing images docker save $(docker images -q) -o docker-images.tar # After installing OrbStack, import images docker load -i docker-images.tar # Verify migration docker images docker ps -a ``` ## Core Operations ### Container Management ```bash # Run container with volume mounting docker run -d -p 3000:3000 -v $(pwd):/app --name myapp node:18 # Execute commands in running container docker exec -it myapp bash docker exec myapp npm install # View container logs with follow docker logs -f myapp # Stop and remove container docker stop myapp && docker rm myapp ``` ### Image Operations ```bash # Build image with BuildKit features docker build -t myapp:latest . docker build --platform linux/amd64,linux/arm64 -t myapp:multi-arch . # Pull specific platform images docker pull --platform linux/amd64 nginx:alpine # Clean up unused images docker image prune -a docker system prune -a --volumes ``` ## OrbStack-Specific Features ### Linux Machine Access ```bash # Access OrbStack Linux environment directly orb # Run commands in Linux context orb -c "apt update && apt install -y curl" # Copy files to/from Linux machine orb push myfile.txt /home/ orb pull /home/myfile.txt ./ ``` ### Performance Optimization ```bash # Check OrbStack status and resource usage orb status # Configure resource limits orb config set cpu_limit 4 orb config set memory_limit 8G # Enable/disable features orb config set kubernetes false orb config set rosetta true # For x86 containers on Apple Silicon ``` ## Development Workflows ### Docker Compose Development ```bash # Start development stack docker-compose up -d # Scale specific services docker-compose up -d --scale worker=3 # View logs for specific service docker-compose logs -f web # Rebuild and restart service docker-compose up -d --build web # Clean shutdown docker-compose down -v ``` ### Multi-Platform Builds ```bash # Setup buildx for multi-platform docker buildx create --use --name orbstack-builder # Build for multiple architectures docker buildx build --platform linux/amd64,linux/arm64 -t myapp:latest --push . # Build and load locally docker buildx build --platform linux/arm64 -t myapp:arm64 --load . ``` ## Decision Trees ### Choose Container Runtime Strategy ``` Development Environment? ├─ Local development only │ └─ Use: docker run with volume mounts ├─ Multi-service application │ └─ Use: docker-compose ├─ Kubernetes development │ └─ Use: orb config set kubernetes true └─ Production simulation └─ Use: Multi-platform builds + resource limits ``` ### Performance Optimization Path ``` Performance Issues? ├─ Slow container startup │ ├─ Enable Rosetta: orb config set rosetta true │ └─ Use smaller base images ├─ High memory usage │ ├─ Set memory limits: orb config set memory_limit 6G │ └─ Clean unused resources: docker system prune -a ├─ Slow file operations │ ├─ Use delegated mounts: -v $(pwd):/app:delegated │ └─ Consider bind mounts for large codebases └─ Network latency └─ Use host networking: --network host ``` ## Troubleshooting ### Common Error Messages **Error: "Cannot connect to the Docker daemon"** ```bash # Check OrbStack status orb status # Restart OrbStack service orb restart # Verify Docker context docker context ls docker context use orbstack ``` **Error: "No space left on device"** ```bash # Check disk usage docker system df # Clean up aggressively docker system prune -a --volumes docker builder prune -a # Check OrbStack disk usage orb status --verbose ``` **Error: "Platform mismatch warnings"** ```bash # Enable Rosetta for x86 containers on Apple Silicon orb config set rosetta true # Explicitly specify platform docker run --platform linux/amd64 myimage:latest # Use multi-arch images when available docker pull --platform linux/arm64 postgres:15 ``` **Error: "Port already in use"** ```bash # Find process using port lsof -i :3000 # Kill process or use different port docker run -p 3001:3000 myapp:latest # Use dynamic port allocation docker run -P myapp:latest ``` ### Performance Issues **Slow Build Times** ```bash # Enable BuildKit cache export DOCKER_BUILDKIT=1 # Use cache mounts in Dockerfile # RUN --mount=type=cache,target=/root/.npm npm install # Build with cache from registry docker buildx build --cache-from myapp:buildcache . ``` **High Resource Usage** ```bash # Monitor resource usage docker stats # Set container resource limits docker run -m 512m --cpus="1.0" myapp:latest # Configure OrbStack limits orb config set memory_limit 4G orb config set cpu_limit 2 ``` ### File Permission Issues ```bash # Fix ownership in bind mounts docker run -u $(id -u):$(id -g) -v $(pwd):/app myapp:latest # Use named volumes for persistent data docker volume create myapp-data docker run -v myapp-data:/data myapp:latest # Set proper permissions in Dockerfile # USER node # WORKDIR /app ``` ### Network Connectivity ```bash # Test container networking docker run --rm alpine ping google.com # Inspect network configuration docker network ls docker network inspect bridge # Use custom networks docker network create myapp-network docker run --network myapp-network myapp:latest ``` ### Debugging Container Issues ```bash # Enter container for debugging docker run -it --entrypoint /bin/sh myapp:latest # Check container filesystem docker exec myapp ls -la /app # Export container for analysis docker export myapp > container.tar # Analyze image layers docker history myapp:latest ``` ## Best Practices - Use `.dockerignore` to exclude unnecessary files - Leverage OrbStack's Rosetta support for better x86 compatibility - Set appropriate resource limits for development containers - Use multi-stage builds to reduce image size - Regular cleanup with `docker system prune` to manage disk space - Enable BuildKit for improved build performance and caching