본문으로 건너뛰기

2파일 체계

amd64/arm64 Docker Compose 2파일 체계를 설명합니다.

왜 2파일인가?​

Multi-SaaS Kit은 CPU 아키텍처별로 최적화된 Docker Compose 파일을 제공합니다.

방식장점단점
단일 파일 + multi-arch 이미지관리 간편일부 이미지 미지원
2파일 체계아키텍처별 최적화파일 2개 관리

선택 이유:

  • 일부 Docker 이미지는 특정 아키텍처만 지원
  • 네이티브 이미지로 최적 성능 보장
  • dev/prod 분리 대신 아키텍처 분리 (환경은 서버 분리로 구분)

파일 구조​

{project}/_docker/
├── docker-compose.amd64.yml   # Intel/AMD (x86_64)
├── docker-compose.arm64.yml   # Apple Silicon, ARM
└── conf/                      # 공유 설정
    ├── nginx/
    ├── php/
    ├── postgres/
    └── redis/

아키텍처별 대상​

파일아키텍처대상 환경
docker-compose.amd64.ymlx86_64Intel/AMD PC, 대부분의 클라우드 서버
docker-compose.arm64.ymlaarch64Apple Silicon Mac, AWS Graviton, Raspberry Pi

자동 선택 메커니즘​

Makefile이 시스템 아키텍처를 자동 감지합니다.

# 아키텍처 감지
ARCH := $(shell uname -m | sed 's/x86_64/amd64/' | sed 's/aarch64/arm64/')

# docker-compose 파일 선택
COMPOSE_FILE = workspace/$(NAME)/_docker/docker-compose.$(ARCH).yml

사용자는 아키텍처를 신경 쓸 필요 없습니다:

# 동일한 명령어로 실행
make up NAME=myproject

# Intel Mac에서 → docker-compose.amd64.yml 사용
# Apple Silicon Mac에서 → docker-compose.arm64.yml 사용

파일 간 차이점​

amd64.yml​

services:
  web:
    build:
      context: ./conf/php
      dockerfile: Dockerfile
    # platform 지정 없음 (기본값 사용)

arm64.yml​

services:
  web:
    build:
      context: ./conf/php
      dockerfile: Dockerfile
      platforms:
        - linux/arm64    # 명시적 플랫폼 지정
    platform: linux/arm64  # 런타임 플랫폼

핵심 차이: arm64에서는 모든 서비스에 platform: linux/arm64를 명시적으로 지정합니다.

이미지별 차이​

서비스amd64arm64
nginxnginx:alpinenginx:alpine (동일)
PHPphp:8.4-fpmphp:8.4-fpm + platform 지정
PostgreSQLpostgres:18postgres:18 + platform 지정
Redisredis:7-alpineredis:7-alpine + platform 지정

수동 선택 방법​

특정 아키텍처로 강제 실행해야 할 경우:

# amd64 강제
docker compose -f workspace/myproject/_docker/docker-compose.amd64.yml up -d

# arm64 강제
docker compose -f workspace/myproject/_docker/docker-compose.arm64.yml up -d
아키텍처 불일치 시

호환되지 않는 아키텍처로 실행하면 에뮬레이션이 활성화되어 성능이 크게 저하됩니다.

새 서비스 추가 시​

양쪽 파일에 모두 추가해야 합니다:

# docker-compose.amd64.yml
services:
  newservice:
    image: some/image:latest
    # ...

# docker-compose.arm64.yml
services:
  newservice:
    image: some/image:latest
    platform: linux/arm64    # 추가
    # ...

아키텍처 확인​

현재 시스템의 아키텍처를 확인하려면:

# 리눅스/macOS
uname -m
# x86_64 → amd64
# aarch64 또는 arm64 → arm64

# Makefile에서 확인
make check-prereq

관련 문서​