Docker Desktop 또는 OrbStack에서 Oxcart로 전환

시작하기 전에

• macOS 26 이상을 실행하는 Apple Silicon Mac.
• 이미지와 볼륨을 복사하는 동안 컨텍스트가 응답하도록 다른 앱을 실행해 두세요.
• 실제로 필요한 항목을 정리하세요. 다시 가져올 수 없는 이미지와 데이터(데이터베이스, 업로드 파일)가 들어 있는 명명된 볼륨입니다. 나머지는 다시 만드는 편이 빠릅니다.
• 먼저 대표적인 Compose 프로젝트 하나로 시험하세요. 서비스가 시작되고 데이터가 있으며 게시된 포트가 응답하는지 확인한 뒤 나머지를 옮기세요.

Oxcart로 이전하는 단계

1. Oxcart를 설치하세요. Oxcart(Apple Silicon, macOS 26 이상)를 다운로드해 엽니다. 설정은 오프라인으로 몇 초면 완료됩니다. 명령줄 도구를 연결하는 도우미를 위해 관리자 암호를 한 번 입력해야 합니다.
2. docker 도구 처리 방법을 결정하세요. Docker Desktop이나 OrbStack이 docker를 설치한 경우 Oxcart는 도구별로 두 버전을 표시하고 교체 전에 확인합니다. Replace는 기본으로 켜져 있으며, Uninstall을 실행하면 다른 앱의 도구를 복원합니다.
3. oxcart 컨텍스트를 선택하세요. 설정 과정에서 oxcart Docker 컨텍스트를 만듭니다. 현재 컨텍스트가 default이고 응답하는 대상이 없을 때만 이를 현재 컨텍스트로 설정하므로, 다른 앱을 사용했다면 보통 직접 docker context use oxcart를 실행해야 합니다.
4. 필요한 이미지를 가져오세요. 다시 가져오거나 다른 앱에서 docker save의 출력을 docker load로 스트리밍하면 태그와 다이제스트가 유지됩니다.
5. 데이터가 있는 볼륨을 옮기세요. 다른 앱의 작은 컨테이너를 통해 각 명명된 볼륨을 tar 파일로 묶은 뒤 Oxcart의 새 볼륨에 풉니다.
6. Compose 프로젝트를 시작하세요. 각 프로젝트 폴더에서 docker compose up -d --wait를 실행합니다. 같은 이름으로 옮긴 볼륨이 사용됩니다.
7. 연결 대상이 고정된 도구를 Oxcart로 지정하세요. Docker 컨텍스트를 따르는 도구는 Oxcart를 자동으로 찾습니다. DOCKER_HOST만 읽는 도구는 해당 값을 oxcart 컨텍스트의 엔드포인트로 설정해야 합니다.

명령

컨텍스트 확인 및 전환

docker context ls

목록에 oxcart와 다른 앱의 컨텍스트가 표시되며 현재 컨텍스트에는 별표가 붙습니다. 다음을 실행하세요.

docker context use oxcart

다른 앱에서 이미지 복사

중간 파일 없이 한 엔진에서 다른 엔진으로 이미지를 직접 스트리밍합니다. 태그와 다이제스트도 함께 옮겨집니다.

# OTHER is the other app's context name from `docker context ls`
OTHER=<other-context>
docker --context "$OTHER" save postgres:17-alpine myapp:dev | docker --context oxcart load

태그가 있는 모든 이미지를 한 번에 가져오려면:

docker --context "$OTHER" images --format '{{.Repository}}:{{.Tag}}' | grep -v '<none>' \
  | xargs docker --context "$OTHER" save | docker --context oxcart load

Dockerfile로 빌드한 이미지는 Oxcart에서 docker build 또는 docker compose build로 다시 빌드하는 편이 더 빠를 때가 많습니다. 벤치마크에서 캐시를 사용한 재빌드는 121 ms가 걸렸습니다.

명명된 볼륨 이전

이 예제는 pgdata라는 Postgres 볼륨을 옮깁니다. 홈 폴더 안의 폴더에 tar 파일을 씁니다. Oxcart는 기본적으로 홈 폴더를 컨테이너와 공유하며 다른 앱도 해당 폴더를 바인드 마운트할 수 있어야 합니다. 복사본의 일관성을 유지하도록 해당 볼륨을 사용하는 컨테이너를 먼저 중지하세요.

mkdir -p ~/volume-move && cd ~/volume-move
# 1. Pack the volume in the other app
docker --context "$OTHER" run --rm -v pgdata:/from -v "$PWD":/backup alpine \
  tar -C /from -czf /backup/pgdata.tgz .
# 2. Unpack it into a new volume in Oxcart
docker --context oxcart volume create pgdata
docker --context oxcart run --rm -v pgdata:/to -v "$PWD":/backup alpine \
  tar -C /to -xzf /backup/pgdata.tgz

Compose는 볼륨 이름을 <project>_<volume> 형식으로 지정합니다. 같은 전체 이름으로 Oxcart 볼륨을 만들면(다른 컨텍스트에서 docker volume ls로 확인) Compose가 해당 볼륨을 사용합니다.

Compose 프로젝트 시작

cd ~/code/myproject
docker compose up -d --wait

상태 확인 종속성, up --wait, 서비스 이름 DNS, init: true, network_mode: service:가 이전처럼 작동합니다. Apple Silicon에서 Docker Compose 사용을 확인하세요.

DOCKER_HOST를 읽는 도구

Oxcart는 /var/run/docker.sock을 생성하거나 교체하지 않습니다. docker CLI, Compose, Buildx, 대부분의 SDK는 현재 컨텍스트를 따릅니다. DOCKER_HOST만 읽는 도구라면 Oxcart를 지정하세요.

export DOCKER_HOST="$(docker context inspect oxcart --format '{{.Endpoints.docker.Host}}')"

컨테이너 안에서는 Testcontainers, docker-outside-of-docker, Portainer, Traefik을 위해 /var/run/docker.sock을 평소처럼 마운트할 수 있습니다. Mac에서 Dev Containers 및 Testcontainers 사용을 확인하세요.

다시 전환

docker context use <other-context>   # back to the other app
docker context use oxcart            # and to Oxcart again

전환 후 달라지는 점

Oxcart 0.1.2는 2026-10-10에 기본 제공 docker 29.9 클라이언트로 측정했습니다. OrbStack 2.2.3과 Docker Desktop 4.94.0은 같은 날 앞서 동일한 Mac과 테스트 하네스에서 docker 29.4로 측정했습니다. 전체 표: Docker Desktop 비교 및 OrbStack 비교.

코딩 에이전트용 로컬 MCP 서버(한 번 붙여넣어 설정), 저장소 및 브랜치별로 묶인 포트, VPN·DNS·방화벽 규칙을 따르는 컨테이너 트래픽도 제공됩니다(네트워킹 가이드).

자주 묻는 질문

먼저 Docker Desktop이나 OrbStack을 제거해야 하나요?

아니요. Oxcart는 자체 oxcart Docker 컨텍스트로 다른 앱과 함께 설치됩니다. docker context use로 전환하세요. 필요한 항목을 모두 옮길 때까지 다른 앱을 유지하세요.

Oxcart가 현재 Docker 컨텍스트를 변경하나요?

현재 컨텍스트가 default이고 응답하는 대상이 없을 때만 변경합니다. 다른 앱의 컨텍스트가 현재 컨텍스트라면 그대로 두며, docker context use oxcart로 직접 선택할 수 있습니다.

이미지와 볼륨이 자동으로 옮겨지나요?

아니요. 각 앱은 자체 이미지와 볼륨을 보관합니다. 이미지를 다시 가져오거나 docker save | docker load로 스트리밍하세요. 데이터가 있는 명명된 볼륨은 위 설명처럼 tar 파일로 옮깁니다. 캐시나 다른 임시 데이터가 있는 볼륨은 다시 만들면 됩니다.

레지스트리 로그인 정보는 어떻게 되나요?

가져오기 중 자격 증명을 요청하면 docker login을 한 번 실행하세요. Oxcart는 docker-credential-osxkeychain을 통해 암호를 macOS 키체인에 저장하며, config.json에는 레지스트리 이름만 보관합니다.

기존 개발 워크플로를 유지할 수 있나요?

네. docker CLI, Compose, Buildx, Dev Containers, Testcontainers를 계속 사용하세요. Oxcart는 Compose의 privileged: true를 포함해 특권 컨테이너를 지원합니다. 먼저 프로젝트 하나를 옮겨 포트와 데이터를 확인한 뒤 준비가 되면 나머지를 전환하세요. 다른 Docker 컨텍스트는 전 과정에서 계속 사용할 수 있습니다.

업데이트해도 컨테이너가 유지되나요?

네. Oxcart 업데이트는 모든 컨테이너, 이미지, 볼륨, 네트워크를 유지합니다.

어떻게 되돌아가나요?

다른 앱의 컨텍스트 이름으로 docker context use를 실행하세요. Oxcart를 제거하면 Uninstall이 교체했던 모든 docker 도구를 복원합니다.

출처와 측정 방법

• 설정, 명령줄 도구, Docker 컨텍스트: 배포된 Oxcart 0.1.3 기준.
• 호환성: 2026-10-10에 Oxcart에서 테스트(태그 및 다이제스트를 유지한 저장과 로드, Compose, 컨테이너 내부 Docker 소켓).
• 벤치마크: Oxcart 0.1.2, OrbStack 2.2.3, Docker Desktop 4.94.0을 2026-10-10에 Apple M5 Max 1대에서 측정했습니다. 각각 CPU 8개와 12 GB로 설정하고 한 번에 한 제품씩 실행했으며 5회 표본의 중앙값입니다.
• 다른 앱의 컨텍스트 이름은 앱과 버전에 따라 다릅니다. docker context ls에서 확인하세요.