Saltar al contenido principal

OrbStack — Runtime de contenedores

Qué es​

OrbStack es el runtime de contenedores y máquinas virtuales Linux para macOS que Wiedii usa como sustituto de Docker Desktop. Expone la API de Docker y kubectl de forma totalmente compatible, pero con arranque en ~2 segundos, consumo de RAM y CPU significativamente menor, y sin licencia comercial para equipos.

Por qué la usamos en Wiedii​

  • Docker Desktop tiene licencia comercial para empresas — no autorizado.
  • Podman Desktop — no autorizado en Wiedii.
  • OrbStack es el estándar: gratuito para uso individual/dev, API 100% compatible con Docker y Kubernetes, integración nativa en macOS (menu bar, Rosetta para x86).

⛔ Si tienes Docker Desktop o Podman instalado, desinstálalo antes de instalar OrbStack para evitar conflictos en el socket Docker.

Instalación​

brew install orbstack

Primer arranque — obligatorio:

Abrir OrbStack desde Launchpad o Spotlight. El onboarding del sistema hace tres cosas:

  1. Instala las CLIs (docker, kubectl, orb) en el PATH
  2. Configura el socket Docker en /var/run/docker.sock
  3. Instala la extensión de red necesaria para los dominios locales

OrbStack debe abrirse al menos una vez manualmente. Sin ese paso, el socket Docker no queda configurado y los comandos docker fallan.

Verificación​

OrbStack no tiene un comando de status en CLI — se verifica por la presencia del icono en la menu bar.

# ✅ OrbStack corriendo = icono visible en la menu bar de macOS

# Verificar que el socket Docker está activo
docker context show        # ✅ orbstack
docker ps                  # ✅ lista de contenedores (vacía si no hay ninguno)

# Verificar kubectl
kubectl version --client   # ✅ Client Version: ...

Si docker context show devuelve default en lugar de orbstack, OrbStack no está corriendo. Abrir la app desde Spotlight o menu bar.

Configuración estándar​

Integración con zsh​

OrbStack añade su integración automáticamente al primer arranque:

# ~/.zprofile — añadido por OrbStack
source ~/.orbstack/shell/init.zsh 2>/dev/null || :

Esta línea activa: Docker socket, kubectl context orbstack, completions de docker, y la CLI orb para máquinas virtuales.

Recursos (ajustar según la máquina)​

OrbStack → ⚙️ Settings → Resources:

  • Memory: 4–8 GB (más no suele ser necesario para dev local)
  • CPU: sin límite por defecto (OrbStack es eficiente)
  • Disk: imagen en ~/.orbstack/data/ — no mover manualmente

Kubernetes local​

OrbStack incluye un cluster Kubernetes de un nodo. Activar desde Settings → Kubernetes → Enable Kubernetes. El context se llama orbstack.

kubectl config use-context orbstack
kubectl get nodes   # ✅ orbstack   Ready   ...

Dominios locales (.orb.local)​

OrbStack asigna automáticamente un dominio <nombre>.orb.local a cada contenedor y VM. Por ejemplo, un contenedor llamado api es accesible en http://api.orb.local desde el Mac sin mapear puertos.

Para que macOS resuelva estos dominios, el desarrollador debe completar la configuración una sola vez:

Paso 1 — Habilitar dominios locales en OrbStack​

Abrir OrbStack → Settings → General → activar "Local domains".

OrbStack solicitará permiso para instalar una extensión de red del sistema.

Paso 2 — Aprobar la extensión de red​

macOS bloqueará la extensión de red por seguridad. Aparecerá una notificación del sistema. Si no aparece:

System Settings → Privacy & Security → bajar hasta la sección Security → buscar el mensaje sobre software de OrbStack bloqueado → clic en "Allow".

Puede requerir autenticación con Touch ID o contraseña de administrador.

Paso 3 — Verificar la resolución de dominios​

# Levantar un contenedor de prueba con nombre explícito
docker run -d --name test-local nginx:alpine

# Comprobar que el dominio resuelve
ping -c 1 test-local.orb.local     # ✅ responde desde la IP de OrbStack
curl http://test-local.orb.local   # ✅ página de bienvenida de nginx

# Limpiar
docker rm -f test-local

Cómo funcionan los dominios​

RecursoDominio
Contenedor apiapi.orb.local
Contenedor postgrespostgres.orb.local
VM ubuntuubuntu.orb.local
Servicio en VM ubuntu en puerto 3000ubuntu.orb.local:3000

Los dominios solo resuelven desde el Mac host. Dentro de los propios contenedores se sigue usando el nombre de servicio del compose network.

💡 Esto elimina la necesidad de editar /etc/hosts o mapear puertos con -p para el desarrollo local.

Comandos clave​

OrbStack es 100% compatible con la CLI de Docker:

# Contenedores
docker ps
docker run --rm -it alpine sh
docker compose up -d
docker compose logs -f servicio

# Imágenes
docker build -t mi-imagen:local .
docker images
docker image rm mi-imagen:local

# Volúmenes y redes
docker volume ls
docker network ls

# Limpiar todo
docker system prune -af

Máquinas virtuales Linux​

orb create ubuntu mi-vm     # crear VM Ubuntu
orb run mi-vm -- bash       # entrar a la VM
orb list                    # listar VMs
orb delete mi-vm            # eliminar VM

Útil para probar scripts de instalación o servicios que requieren Linux nativo.

Integración con docker compose​

Wiedii usa docker compose v2 (integrado en OrbStack) — no docker-compose v1:

# ✅ Correcto
docker compose up -d

# ❌ Obsoleto
docker-compose up -d

Troubleshooting rápido​

docker ps falla / "Cannot connect to the Docker daemon":

open -a OrbStack   # arrancar OrbStack
# Verificar icono en menu bar → debe aparecer
docker context show   # debe devolver: orbstack

Conflicto con Docker Desktop (si quedó instalado):

# Desinstalar Docker Desktop
# Applications → Docker.app → mover a Papelera
# Luego abrir OrbStack para que tome el socket
open -a OrbStack

Dominio .orb.local no resuelve:

# 1. Verificar que los dominios locales están habilitados
# OrbStack → Settings → General → Local domains ✅

# 2. Verificar la extensión de red aprobada
# System Settings → Privacy & Security → Security → OrbStack → Allow

# 3. Verificar el resolver
cat /etc/resolver/orb   # debe existir este archivo

# 4. Probar resolución manual
dscacheutil -q host -a name test.orb.local

Kubernetes no responde:

kubectl config use-context orbstack
kubectl cluster-info
# Si falla: OrbStack → Settings → Kubernetes → Reset Kubernetes

Imágenes ARM vs x86 en Apple Silicon:

docker run --platform linux/amd64 imagen:tag
# OrbStack usa Rosetta automáticamente para imágenes x86

Referencias​