Recommend Apple container for Mac setup (blocked on VS Code Reopen in Container)

Bắt đầu với README và .devcontainer/devcontainer.json, sau đó đọc tracker vscode-remote-release#11012 được liên kết. Xác minh xem Reopen in Container có hỗ trợ Apple container hay không, bao gồm Node 24 Feature và postCreateCommand. Hoàn tất khi các tiêu chí chấp nhận được đáp ứng mà không thay đổi khuyến nghị về OrbStack quá sớm.

Prefer Apple container as the Mac recommendation for the documented VS Code Dev Containers path. It should compete with (and, on Mac, replace) OrbStack and the other Docker-engine hosts. Linux and Windows stay on Docker/Podman/Colima; Apple container does not run there.

This is blocked. Stock Dev Containers: Reopen in Container does not drive Apple container. Upstream tracker:

https://github.com/microsoft/vscode-remote-release/issues/11012

Why this is the Mac preference

README already states the criterion:

We would prefer an open-source-licensed Docker implementation that runs at native speed on Mac, Linux and Windows.

Today the Mac line is OrbStack (proprietary, Docker-compatible, fast) with Colima as the slower open-source alternative. Apple container 1.4.1 is Apache-2.0, first-party, and runs each Linux OCI image as its own lightweight VM on Apple silicon + macOS 26. That matches the license preference on Mac better than OrbStack. It does not satisfy the cross-platform part of that sentence, so it is a Mac-only recommendation, not a universal Docker replacement.

Current documented approach

From README:

1. Install VS Code and the Dev Containers extension.
2. Install a Docker host (Mac: OrbStack).
3. Run Dev Containers: Reopen in Container.

.devcontainer/devcontainer.json is the environment:

• Image: mcr.microsoft.com/devcontainers/ruby:3.3-bookworm (minor tag matches .ruby-version).
• Feature: ghcr.io/devcontainers/features/node:2 with Node 24 (must stay in sync with .node-version). Yarn 4 is via Corepack, not the feature.
• postCreateCommand: Corepack → Yarn 4.18.0 → yarn install --immutable → bundle install.

The non-container path is still valid: rv for Ruby (.ruby-version) and fnm for Node (.node-version). package.json scripts call rv run bundle exec …, so they are written for that host toolchain, not for a Linux image that already has the right ruby on PATH.

What works today with Apple container (no Docker)

Verified on Apple silicon, macOS 26.6.2, container CLI 1.4.1, container system start --enable-kernel-install.

OCI run/build:

container run --rm alpine echo hello
container image pull python:alpine
container build --tag web-test --file /abs/path/Dockerfile .
container run -d --name web web-test
container exec web ls /
container logs web
container stop web

--file Dockerfile is resolved against the process cwd, not the build context directory. Pass an absolute path.

Bind mounts work, including the destination= alias and readonly:

container run --rm \
  --mount source="$PWD",destination=/work,readonly \
  -w /work \
  python:alpine python -c 'open("README.md").read()'

This repo's Jekyll site builds and serves from Apple container if you skip Dev Containers entirely:

container run -d --name site-dev --cpus 4 --memory 4G \
  --volume "$PWD:/work" --workdir /work \
  ruby:3.3.4-bookworm sleep 36000
container exec site-dev bash -lc 'bundle install && bundle exec jekyll build'
container exec site-dev bash -lc 'bundle exec jekyll serve --host 0.0.0.0 --port 4000 --livereload'

Guest Ruby is 3.3.4. bundle exec jekyll build writes build/. The server answers on the container's vmnet IPv4 (192.168.64.x:4000). Browser load of that URL shows the site. 127.0.0.1:4000 does not: this site-dev was not started with -p, and when -p 8000:8000 / -p 127.0.0.1:8000:8000 was tested on a Python HTTP server, publishedPorts showed in container inspect but curl to localhost connected and hung. Curl to the container IP returned 200. Same localhost-vs-IP pattern is reported on the VS Code issue.

Do not document container machine for this template. Default home-mount is rw (Mac $HOME at the same path). First container machine run after create often fails with Operation not supported by device. alpine:latest also crashed on missing /sbin/openrc; Apple's examples use alpine:3.22.

Where Reopen in Container stops

Dev Containers: Reopen in Container is not container run. It:

1. Reads .devcontainer/devcontainer.json.
2. Talks to a Docker Engine API (unix socket) plus a docker CLI.
3. Pulls/builds, creates the container, bind-mounts the workspace.
4. Installs Dev Container Features (this repo's Node 24 is one).
5. Runs postCreateCommand.
6. Installs vscode-server and reopens the window attached to that guest.

Apple container has no Docker socket and no Compose. Setting dev.containers.dockerPath / dockerComposePath to container does not work: the extension speaks Docker's HTTP API and Docker CLI JSON, not Apple's CLI. Without a Docker engine, VS Code reports that Docker is missing (Docker version 17.12.0 or later required).

Microsoft's current support, from vscode-remote-release#11012 (Backlog, assigned to @chrmarti):

• Dev Containers 0.424.0-pre-release added Dev Containers: Attach to Running Apple Container behind dev.containers.experimentalAppleContainerSupport.
• You start the VM yourself (container run -d … sleep infinity), then attach.
• devcontainer.json is not applied. Features are not installed. postCreateCommand is not run. You pick the workspace folder by hand.
• Automatic port discovery is incomplete; forwarding sometimes needs a manual Ports-panel add.
• Attach to mcr.microsoft.com/devcontainers/… images has been reported to hang (also discussed in apple/container#293).

That is attach, not Reopen. It is not a replacement for the README's one-command onboarding.

This repo's Node install is a Feature (ghcr.io/devcontainers/features/node:2). Features are applied by the Dev Containers toolchain talking to Docker. A plain container run of the Ruby image does not install Node 24. Baking Node into a Dockerfile would drop that dependency; that is a possible fallback if the adapter never covers Features.

yarn build / yarn dev inside a Linux guest will fail unless rv is installed there. Those scripts are for the host rv path. Inside ruby:3.3.4-bookworm, the matching command is bundle exec … (same as CI's ruby/setup-ruby). Host Yarn PnP (.pnp.cjs) is Mac-generated and untracked; do not reuse it in a Linux guest.

Adapters that exist and are not the template default

Approach	What it is	Why it is not the README line yet
socktainer	Docker Engine API v1.51 (partial) on a unix socket in front of Apple container	Closest "pretend to be Docker" adapter. API is partial; Reopen + Features against this file is unproven. Extra daemon to install.
CLI shims (docker → container)	Translate some flags	VS Code copies files, execs, watches events, installs Features. A flag translator is too thin.
wcgomes/apple-devcontainers	Swift CLI that reads devcontainer.json and can --vscode attach	Third-party; not the stock Reopen command.
Apple Container Manager	Separate "Reopen" via Remote-SSH	Different config path (.appcontainer/devcontainer.json), requires sshd in the image.

Acceptance

Keep OrbStack (and Colima) on the README until one of these is true:

1. Dev Containers: Reopen in Container against this .devcontainer/devcontainer.json works with only Apple container (and whatever Microsoft ships). Features install Node 24. postCreateCommand runs. The window attaches at the workspace mount. Tracked on vscode-remote-release#11012.
2. Or a Docker-socket adapter (socktainer or equivalent) is complete enough that the same Reopen path works, and we are willing to document installing that adapter.

Then:

• README Mac Docker-host sentence recommends Apple container (brew install container or Apple's signed pkg, then container system start).
• Document that you talk to published services on the container IPv4 until localhost -p is reliable.
• Keep the rv / fnm host path for people who do not want a container.
• Linux/Windows still recommend a Docker engine.
• Do not document container machine for this project.

Until the blocker lifts, do not change the OrbStack recommendation. The CLI recipe above is a verified Mac alternative, not a substitute for Reopen.