Docker 문제 해결

이 페이지는 제너레이터가 생성하는 Docker 빌드에서 발생할 수 있는 문제에 대한 해결 방법을 제공합니다. 제너레이터가 따르는 패턴에 대한 배경 정보는 Docker 번들링 가이드를 참조하세요.

크로스 플랫폼 빌드

ts#strands-agent, py#strands-agent, ts#mcp-server, py#mcp-server와 같은 제너레이터는 호스트 아키텍처와 관계없이 linux/arm64 (Graviton) 이미지를 생성합니다. x86_64 호스트에서 arm64 이미지를 빌드하거나 Apple Silicon에서 amd64 이미지를 빌드하려면 로컬 Docker 설치에서 멀티 플랫폼 빌드 지원이 필요합니다.

멀티 플랫폼 빌드가 설정되지 않은 경우, 증상은 Dockerfile에 따라 다릅니다:

Dockerfile에 RUN 단계가 있는 경우 (TypeScript 제너레이터는 번들링할 수 없는 종속성에 대해 RUN npm install을 실행): 빌드가 중간에 실패하며 다음 오류가 발생합니다
Terminal window
```
exec /bin/sh: exec format error
```
Dockerfile이 COPY만 사용하는 경우 (Python 제너레이터): 빌드는 성공하지만 나중에 docker run이 실패하며 다음 오류가 발생합니다
Terminal window
```
exec /usr/local/bin/python: exec format error
```
대상 플랫폼에 대한 베이스 이미지를 사용할 수 없는 경우: FROM 단계에서 빌드가 실패하며 no match for platform in manifest 오류가 발생합니다.

멀티 플랫폼 빌드 활성화

Docker Desktop (Mac / Windows / Linux)은 기본적으로 QEMU 에뮬레이션이 활성화되어 제공되므로 일반적으로 추가 설정이 필요하지 않습니다.

Linux 호스트 (CI 러너 포함)는 커널에 등록된 QEMU binfmt 핸들러가 필요합니다. 머신당 한 번 설치하세요:

docker run --privileged --rm tonistiigi/binfmt --install all

지원되는 플랫폼이 프로젝트 대상과 일치하는지 확인하세요:

docker buildx inspect --bootstrap

Platforms: 줄에 linux/arm64가 포함되어야 합니다.

에뮬레이트된 아키텍처에서의 느린 빌드

x86_64 호스트에서 arm64 이미지를 빌드하거나 (또는 그 반대) QEMU를 사용하여 각 명령을 에뮬레이트하므로 네이티브 빌드보다 몇 배 느릴 수 있습니다. 제너레이터는 Dockerfile 외부에서 종속성 해결을 수행하여 이를 완화합니다 — Docker 번들링을 참조하세요. 여전히 느린 Docker 빌드가 발생하는 경우:

Nx를 통해 bundle / docker 타겟을 실행하고 있는지 확인하세요 (nx docker my-project) 그러면 번들이 실행 간에 캐시됩니다.
CI에서는 QEMU를 완전히 피하기 위해 네이티브 ARM 러너(예: GitHub Actions의 ubuntu-24.04-arm)를 고려하세요.

`cdk deploy` / `nx apply` 시 빌드 컨텍스트 누락

생성된 docker 타겟은 빌드 컨텍스트를 dist/packages/<project>/docker/... (Python) 또는 dist/packages/<project>/bundle/... (TypeScript)에 작성하며, 생성된 infrastructure as code는 해당 디렉터리를 가리킵니다. synth 또는 apply할 때 해당 디렉터리가 존재하지 않으면 ENOENT 또는 “directory does not exist”와 같은 오류가 표시됩니다.

제너레이터는 docker 타겟을 build의 종속성으로 선언하므로 nx build (또는 생성된 nx deploy / nx apply 타겟)는 CDK 또는 Terraform이 실행되기 전에 빌드 컨텍스트를 생성합니다. cdk 또는 terraform을 직접 호출하는 경우 먼저 docker 단계를 실행하세요:

nx run my-project:docker

추가 자료

Docker — Multi-platform builds
Docker 번들링 가이드 — 제너레이터가 따르는 패턴.