Migration Guide: Switching from Docker Desktop for Mac to Orbstack

1. Prerequisites

  • macOS with Homebrew: Ensure Homebrew is installed on your Mac.

  • Basic CLI Skills: Familiarity with terminal commands and environment variables.

2. Installation Steps

a. Install Orbstack

You have two options:

  • Via Homebrew:
    Open your terminal and run:

brew install orbstack

  • Direct Download:
    Visit orbstack.dev to download the latest version.

b. Configure Your Shell Environment

Set an important environment variable. Add this line to your shell configuration file (e.g., ~/.bashrc or ~/.zshrc):

export SKAFFOLD_PUSH=false

This is crucial because Skaffold doesn’t recognize Orbstack as a local development environment and may attempt to push local images to your remote registry if not configured properly.

c. Terminal Commands Setup

If Orbstack doesn’t automatically adjust your terminal settings, manually run these commands:

  • Switch Docker Context:

docker context use orbstack

  • Switch Kubernetes Context:

kubectl config use-context orbstack

These commands ensure that both Docker and Kubernetes point to Orbstack instead of Docker Desktop.

3. Running Orbstack

a. Launch the Orbstack App

Open the Orbstack application from your Applications folder or via Spotlight.

b. Choose Your Mode

When prompted to select an environment (Docker / Kubernetes / Linux), choose the Docker option for Docker container functionality.

c. Configure Settings

System Settings:

  • RAM: Allocate 48GB of RAM for optimal performance (assuming apple silicon macs)

  • Processors: Enable all available processors to fully leverage your hardware capabilities.

Network Settings:

  • Enable: Allow access to container domains and IPs

d. Login using your apothesource gmail account so a license is allocated.

Kubernetes Settings:

  • Enable Kubernetes: If you work with Kubernetes, enable the K8s cluster for orchestration integration.

  • Enable: Expose services to local network devices

4. Additional Tips & Troubleshooting

  • Double-Check Environment Variables:
    Confirm that SKAFFOLD_PUSH is correctly set to avoid any unexpected behavior with image pushes.

  • Resource Allocation:
    Ensure your system can handle the allocated resources (48GB RAM and all processors). Adjust based on your workload requirements.

5 Uninstall Docker Desktop once Orbstack has been validating build a service locally