Apple Silicon의 Docker Compose: amd64 이미지, Rosetta, 상태 확인

arm64 우선, 필요할 때 amd64

M 시리즈 Mac은 arm64 Linux 커널에서 Linux 컨테이너를 실행합니다. 다중 아키텍처 이미지(postgres, redis, node, python 및 대부분의 공식 이미지)를 가져오면 Docker가 arm64 변형을 자동 선택하여 네이티브 속도로 실행합니다.

오래된 내부 이미지, 공급업체 도구, 플랫폼 플래그 없이 Intel 노트북이나 CI 러너에서 빌드한 이미지 등 일부 이미지는 여전히 amd64만 제공합니다. 이런 경우 플랫폼을 명시하세요.

services:
  legacy-tool:
    image: example/amd64-only-tool:1.4
    platform: linux/amd64

Oxcart는 Apple의 x86-64 변환 기술인 Rosetta로 amd64 이미지를 실행합니다. Buildx로 amd64 이미지를 빌드하고 로드하면 엔진에서 로컬로 실행할 수 있습니다. docker run --rm --platform linux/amd64 alpine uname -m으로 컨테이너가 실제 사용하는 아키텍처를 확인하면 x86_64가 출력됩니다.

전체 예제

Postgres 데이터베이스, 현재 폴더에서 빌드되며 데이터베이스가 정상 상태가 될 때까지 기다리는 API, 프로필로 활성화하는 amd64 전용 도구의 예제입니다.

services:
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_PASSWORD: dev
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 2s
      timeout: 3s
      retries: 15

  api:
    build: .
    init: true
    environment:
      DATABASE_URL: postgres://postgres:dev@db:5432/postgres
    ports:
      - "127.0.0.1:8080:8080"
    depends_on:
      db:
        condition: service_healthy

  legacy-tool:
    image: example/amd64-only-tool:1.4
    platform: linux/amd64
    profiles: ["tools"]

volumes:
  pgdata:

각 부분의 역할:

• healthcheck는 Postgres가 단순히 시작된 것이 아니라 실제로 연결을 받을 준비가 되었는지 Compose에 알려 줍니다.
• depends_on: condition: service_healthy는 해당 확인을 통과할 때까지 API를 대기시킵니다.
• init: true는 작은 init을 PID 1로 실행해 시그널이 프로세스에 전달되게 하고 좀비 프로세스를 회수합니다. 그러면 docker stop이 시간 초과를 기다리지 않고 정상 종료됩니다.
• 127.0.0.1:8080:8080은 Mac의 루프백에만 API를 게시합니다. 주소를 지정하지 않으면 게시된 포트가 Mac의 모든 IPv4 주소에서 수신하므로 같은 네트워크의 다른 머신도 접근할 수 있습니다.
• pgdata는 명명된 볼륨입니다. 데이터는 docker compose down 이후에도 유지되며 down -v로만 삭제됩니다.

Apple Silicon에서 Compose 스택 실행

1. 도구를 확인하세요. docker compose version과 docker context show를 실행합니다. Oxcart는 Docker Compose 5.6.0, docker CLI 29.9.0, Buildx 0.38.0을 제공하며 컨텍스트 이름은 oxcart입니다.
2. compose 파일을 작성하세요. 앱이 기다리는 모든 서비스에 healthcheck를 추가하고, 종속 서비스는 depends_on: condition: service_healthy로 기다리게 하세요.
3. 시작하고 정상 상태를 기다리세요. docker compose up -d --build --wait를 실행합니다. 모든 서비스가 실행 중이고 정상 상태가 되면 명령이 반환되며, 그렇지 않은 서비스가 있으면 실패합니다.
4. 포트를 확인하세요. docker compose ps를 실행하거나 Oxcart의 Ports 화면을 여세요. 각 게시된 포트의 준비 완료, 대기 중, 실패 상태와 그 이유를 표시합니다.
5. 반복 개발하세요. 코드를 수정하고 docker compose up -d --build api를 실행합니다. 변경되지 않은 빌드 단계는 캐시를 사용합니다.
6. 정리하세요. docker compose down으로 컨테이너를 중지하고 삭제하세요. 명명된 볼륨도 삭제하려면 docker compose down -v를 실행하세요.

더 빠른 재빌드

Compose는 Buildx와 BuildKit을 통해 빌드합니다. Dockerfile에서 종속성 설치를 COPY . .보다 앞에 두면 코드가 바뀌어도 위의 모든 캐시 레이어를 재사용할 수 있습니다. Oxcart에서 벤치마크 프로젝트의 캐시 빌드는 121 ms, 로컬 컨텍스트를 사용한 캐시 없는 빌드는 341 ms로 둘 다 테스트한 세 런타임 중 가장 빨랐습니다. 짧은 반복 작업에서 절약한 시간이 쌓입니다. docker run --rm은 42 ms, 컨테이너 20개 중지 및 삭제는 77 ms였습니다.

Oxcart 0.1.2는 2026-10-10에 기본 제공 docker 29.9 클라이언트로 측정했습니다. 다른 런타임은 같은 날 앞서 동일한 Mac과 테스트 하네스에서 docker 29.4로 측정했습니다. Apple M5 Max에서 각각 CPU 8개와 12 GiB로 설정하고 한 번에 한 런타임씩 실행했습니다.

포트, Mac, 다른 서비스

• 포트 구문은 Docker와 같습니다. TCP와 UDP, 임시 포트("127.0.0.1::8080"), IPv4와 IPv6에서 수신하는 "[::]:8080:80"을 지원합니다. TCP와 UDP는 같은 호스트 포트 번호를 공유할 수 있습니다.
• 컨테이너에서 Mac 접근: host.docker.internal을 통해 컨테이너와 빌드 단계에서 Mac의 127.0.0.1에 바인딩된 서비스에 TCP로 접근할 수 있습니다.
• 로컬 레지스트리: 레지스트리 컨테이너를 포트 5000에 게시하면 docker push localhost:5000/app으로 접근할 수 있습니다.
• 사이드카: network_mode: service:api는 컨테이너를 다른 서비스의 네트워크 네임스페이스에 넣어 해당 서비스의 localhost를 공유하게 합니다.

VPN, DNS, 방화벽, 네트워크 경로 보호 방식은 Mac의 컨테이너 네트워킹을 확인하세요.

명명된 볼륨과 바인드 마운트

데이터베이스나 빌드가 많이 쓰는 데이터에는 명명된 볼륨을 사용하세요. node_modules, 패키지 캐시, 데이터베이스 파일 등이 해당합니다. 데이터는 엔진 자체 저장소 안에 유지됩니다. Oxcart의 명명된 볼륨은 작은 파일 생성, stat, 읽기, 삭제 작업 1,000회를 17.8 ms에 수행해 테스트한 세 런타임 중 가장 빨랐습니다.

Mac에서 편집하는 소스에는 바인드 마운트를 사용하세요. Oxcart는 기본적으로 홈 폴더, /private/tmp, /private/var/folders를 읽기/쓰기 방식으로 컨테이너와 공유합니다. Mac에서 수정하면 컨테이너에 반영되고 컨테이너에서 수정하면 Mac에 반영됩니다. 한 가지 제한은 Mac에서 변경한 파일이 컨테이너 안에서 inotify 이벤트를 발생시키지 않는다는 점입니다. 컨테이너 안의 파일 감시기가 편집기의 수정을 감지해야 한다면 폴링을 사용하세요.

문제 해결

자주 묻는 질문

Docker Compose는 Apple Silicon Mac에서 작동하나요?

네. Compose는 arm64에서 네이티브로 실행되며 대부분의 공식 이미지는 arm64 변형을 제공합니다. Oxcart는 Docker Compose 5.6.0을 포함하며 호환성 검사에는 여러 서비스, 상태 확인 종속성, up --wait, build, down, 서비스 이름 DNS, init: true, network_mode: service:가 포함됩니다.

M 시리즈 Mac에서 amd64(x86-64) 이미지를 어떻게 실행하나요?

서비스에 platform: linux/amd64를 설정하거나 docker run에 --platform linux/amd64를 전달하세요. Oxcart는 Rosetta로 amd64 이미지를 실행합니다. 네이티브 arm64 이미지가 있다면 우선 사용하고, arm64 빌드가 없는 이미지에 amd64를 사용하세요.

"exec format error"는 무슨 뜻인가요?

컨테이너가 자신이 실행되는 CPU 아키텍처와 다른 아키텍처용 바이너리를 실행하려 했다는 뜻입니다. 보통 이미지나 내부 바이너리가 amd64 전용입니다. 해당 서비스에 platform: linux/amd64를 추가하거나 arm64용으로 이미지를 다시 빌드하세요.

컨테이너가 실행 중인데 앱에 "connection refused"가 표시되는 이유는 무엇인가요?

가장 흔한 원인은 서버가 컨테이너 내부의 127.0.0.1에서 수신하는 것입니다. 게시된 포트는 루프백이 아니라 컨테이너의 네트워크 인터페이스에 도달하므로 서버는 0.0.0.0에서 수신해야 합니다. Oxcart의 Ports 화면은 이 상황을 명확히 표시합니다.

다른 서비스가 준비될 때까지 한 서비스를 기다리게 하려면 어떻게 하나요?

의존 대상 서비스에 healthcheck를 추가하고 이를 사용하는 서비스에 depends_on: { db: { condition: service_healthy } }를 추가하세요. 그러면 docker compose up --wait는 모든 서비스가 정상 상태가 된 뒤에만 반환됩니다.

컨테이너에서 Mac에 실행 중인 서버에 접근할 수 있나요?

네. host.docker.internal을 사용하세요. Oxcart에서는 컨테이너와 빌드에서 Mac의 127.0.0.1에 바인딩된 서비스에 TCP로 접근할 수 있습니다.

데이터베이스에는 명명된 볼륨과 바인드 마운트 중 무엇을 써야 하나요?

데이터베이스 데이터에는 엔진 자체 저장소 안에 보관되는 명명된 볼륨을 사용하세요. Mac에서 편집하는 소스 코드에는 바인드 마운트를 사용하세요. Oxcart의 명명된 볼륨은 작은 파일 생성, stat, 읽기, 삭제 작업 1,000회를 17.8 ms에 수행했습니다.

출처와 측정 방법

• 호환성: Oxcart에서 검증된 통합 방식(docker CLI, 상태 확인 종속성을 사용하는 Compose, up --wait, init: true, network_mode: service:, Buildx, Rosetta를 통한 amd64).
• 속도 수치: Oxcart 0.1.2, 2026-10-10, Apple M5 Max, CPU 8개 및 12 GiB, 준비 실행 후 5회 표본의 중앙값. 다른 런타임은 같은 날 앞서 동일한 Mac과 테스트 하네스에서 docker 29.4 클라이언트로 측정했습니다.
• 기본 제공 도구: docker 29.9.0, Docker Compose 5.6.0, Buildx 0.38.0.