Docker Compose에서 서비스 정의하기

서비스는 애플리케이션 안의 컴퓨팅 리소스에 대한 추상적인 정의로, 다른 구성 요소와 독립적으로 확장하거나 교체할 수 있어요. 서비스는 플랫폼이 복제 요구사항과 배치 제약에 따라 실행하는 일련의 컨테이너에 의해 뒷받침돼요. 서비스는 컨테이너에 의해 뒷받침되므로 Docker 이미지와 런타임 인자 집합으로 정의돼요. 서비스 내의 모든 컨테이너는 이 인자들로 동일하게 생성돼요.

Compose 파일은 services 최상위 요소를 선언해야 하는데, 키가 서비스 이름의 문자열 표현이고 값이 서비스 정의인 맵이에요. 서비스 정의는 각 서비스 컨테이너에 적용되는 구성을 담아요.

각 서비스는 서비스용 Docker 이미지를 만드는 방법을 정의하는 build 섹션도 포함할 수 있어요. Compose는 이 서비스 정의를 사용해 Docker 이미지 빌드를 지원해요. 사용하지 않으면 build 섹션은 무시되고 Compose 파일은 여전히 유효한 것으로 간주돼요. 빌드 지원은 Compose Spec의 선택적 측면이며, Compose Build Specification 문서에 자세히 설명돼 있어요.

각 서비스는 컨테이너를 실행하기 위한 런타임 제약과 요구사항을 정의해요. deploy 섹션은 이 제약들을 그룹화하고 플랫폼이 사용 가능한 리소스와 컨테이너 요구사항에 가장 잘 맞도록 배포 전략을 조정하게 해 줘요. 배포 지원은 Compose Spec의 선택적 측면이며, Compose Deploy Specification 문서에 자세히 설명돼 있어요. 구현되지 않으면 deploy 섹션은 무시되고 Compose 파일은 여전히 유효한 것으로 간주돼요.

예시 (Examples)

간단한 예시

다음 예시는 Docker Compose로 두 개의 간단한 서비스를 정의하고 이미지를 설정하며, 포트를 매핑하고 기본 환경 변수를 구성하는 방법을 보여 줘요.

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"

  db:
    image: postgres:18
    environment:
      POSTGRES_USER: example
      POSTGRES_DB: exampledb

고급 예시

다음 예시에서 proxy 서비스는 Nginx 이미지를 사용하고 로컬 Nginx 구성 파일을 컨테이너에 마운트하며 포트 80을 노출하고 backend 서비스에 의존해요.

backend 서비스는 backend 디렉토리에 있는 Dockerfile에서 이미지를 빌드하며, builder 스테이지에서 빌드하도록 설정돼요.

services:
  proxy:
    image: nginx
    volumes:
      - type: bind
        source: ./proxy/nginx.conf
        target: /etc/nginx/conf.d/default.conf
        read_only: true
    ports:
      - 80:80
    depends_on:
      - backend

  backend:
    build:
      context: backend
      target: builder

더 많은 예시 Compose 파일은 Awesome Compose 샘플을 살펴보세요.

속성 (Attributes)

`annotations`

annotations는 컨테이너에 대한 주석을 정의해요. annotations는 배열이나 맵을 사용할 수 있어요.

annotations:
  com.example.foo: bar

annotations:
  - com.example.foo=bar

`attach`

attach가 정의되고 false로 설정되면 Compose는 명시적으로 요청할 때까지 서비스 로그를 수집하지 않아요.

기본 서비스 구성은 attach: true예요.

`build`

build는 Compose Build Specification에 정의된 대로 소스에서 컨테이너 이미지를 만들기 위한 빌드 구성을 지정해요.

`blkio_config`

blkio_config는 서비스에 대한 블록 I/O 제한을 설정하는 구성 옵션 집합을 정의해요.

services:
  foo:
    image: busybox
    blkio_config:
       weight: 300
       weight_device:
         - path: /dev/sda
           weight: 400
       device_read_bps:
         - path: /dev/sdb
           rate: '12mb'
       device_read_iops:
         - path: /dev/sdb
           rate: 120
       device_write_bps:
         - path: /dev/sdb
           rate: '1024k'
       device_write_iops:
         - path: /dev/sdb
           rate: 30

`device_read_bps`, `device_write_bps`

주어진 디바이스에 대한 읽기/쓰기 작업의 초당 바이트 제한을 설정해요. 목록의 각 항목은 두 개의 키를 가져야 해요.

path: 영향받는 디바이스의 심볼릭 경로 정의.
rate: 바이트 수를 나타내는 정수 값 또는 바이트 값을 표현하는 문자열.

`device_read_iops`, `device_write_iops`

주어진 디바이스에 대한 읽기/쓰기 작업의 초당 작업 수 제한을 설정해요. 목록의 각 항목은 두 개의 키를 가져야 해요.

path: 영향받는 디바이스의 심볼릭 경로 정의.
rate: 허용된 초당 작업 수를 나타내는 정수 값.

`weight`

다른 서비스에 비해 서비스에 할당된 대역폭의 비율을 수정해요. 10~1000 사이의 정수 값을 가지며 기본값은 500이에요.

`weight_device`

디바이스별로 대역폭 할당을 세밀하게 조정해요. 목록의 각 항목은 두 개의 키를 가져야 해요.

path: 영향받는 디바이스의 심볼릭 경로 정의.
weight: 10~1000 사이의 정수 값.

`cpu_count`

cpu_count는 서비스 컨테이너에 사용 가능한 CPU 수를 정의해요.

`cpu_percent`

cpu_percent는 사용 가능한 CPU의 사용 가능한 백분율을 정의해요.

`cpu_shares`

cpu_shares는 정수 값으로 다른 컨테이너에 대한 서비스 컨테이너의 상대적 CPU 가중치를 정의해요.

`cpu_period`

cpu_period는 플랫폼이 Linux 커널 기반일 때 CPU CFS(Completely Fair Scheduler) 주기를 구성해요.

`cpu_quota`

cpu_quota는 플랫폼이 Linux 커널 기반일 때 CPU CFS(Completely Fair Scheduler) 할당량을 구성해요.

`cpu_rt_runtime`

cpu_rt_runtime은 실시간 스케줄러를 지원하는 플랫폼의 CPU 할당 파라미터를 구성해요. 마이크로초 단위의 정수 값 또는 duration(기간)일 수 있어요.

 cpu_rt_runtime: '400ms'
 cpu_rt_runtime: '95000'

`cpu_rt_period`

cpu_rt_period는 실시간 스케줄러를 지원하는 플랫폼의 CPU 할당 파라미터를 구성해요. 마이크로초 단위의 정수 값 또는 duration(기간)일 수 있어요.

 cpu_rt_period: '1400us'
 cpu_rt_period: '11000'

`cpus`

cpus는 서비스 컨테이너에 할당할 (잠재적으로 가상) CPU 수를 정의해요. 이는 분수(fractional) 숫자예요. 0.000은 제한 없음을 의미해요.

설정되면 cpus는 Deploy Specification의 cpus 속성과 일치해야 해요.

`cpuset`

cpuset는 실행을 허용할 명시적 CPU를 정의해요. 범위 0-3이나 목록 0,1일 수 있어요.

`cap_add`

cap_add는 추가 컨테이너 capabilities을 문자열로 지정해요.

cap_add:
  - ALL

`cap_drop`

cap_drop는 제거할 컨테이너 capabilities을 문자열로 지정해요.

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN

`cgroup`

cgroup은 참여할 cgroup 네임스페이스를 지정해요. 설정하지 않으면 지원되는 경우 어떤 cgroup 네임스페이스를 사용할지 선택하는 것은 컨테이너 런타임의 결정이에요.

host: 컨테이너 런타임 cgroup 네임스페이스에서 컨테이너를 실행.
private: 자체 전용 cgroup 네임스페이스에서 컨테이너를 실행.

`cgroup_parent`

cgroup_parent는 컨테이너의 선택적 부모 cgroup을 지정해요.

cgroup_parent: m-executor-abcd

`command`

command는 컨테이너 이미지가 선언한 기본 명령(예: Dockerfile의 CMD)을 재정의해요.

command: bundle exec thin -p 3000

값이 null이면 이미지의 기본 명령이 사용돼요.

값이 [](빈 목록) 또는 ''(빈 문자열)이면 이미지가 선언한 기본 명령은 무시되거나, 다시 말해 비어 있도록 재정의돼요.

[!NOTE]

Dockerfile의 CMD 명령과 달리 command 필드는 이미지에 정의된 SHELL 명령의 컨텍스트에서 자동으로 실행되지 않아요. command가 환경 변수 확장 같은 셸 특정 기능에 의존한다면 셸 안에서 명시적으로 실행해야 해요. 예를 들면:
command: /bin/sh -c 'echo "hello $$HOSTNAME"'

값은 Dockerfile이 사용하는 exec-form 구문과 유사한 목록일 수도 있어요.

`configs`

configs는 서비스가 Docker 이미지를 다시 빌드하지 않고도 동작을 조정하게 해 줘요. 서비스는 configs 속성으로 명시적으로 허가받았을 때만 configs에 접근할 수 있어요. 두 가지 다른 구문 변형이 지원돼요.

Compose는 플랫폼에 config가 존재하지 않거나 Compose 파일의 configs 최상위 요소에 정의되어 있지 않으면 오류를 보고해요.

configs에는 짧은 구문과 긴 구문이라는 두 가지 구문이 정의돼 있어요.

서비스에 여러 configs에 대한 접근을 허용할 수 있고, 긴·짧은 구문을 섞을 수 있어요.

짧은 구문 (Short syntax)

짧은 구문 변형은 config 이름만 지정해요. 이는 컨테이너에 config 접근을 허용하고 서비스 컨테이너 파일시스템에 파일로 마운트해요. 컨테이너 내 마운트 지점 위치는 Linux 컨테이너에서는 /<config_name>, Windows 컨테이너에서는 C:\<config-name>이 기본값이에요.

다음 예시는 짧은 구문으로 redis 서비스에 my_config와 my_other_config configs에 대한 접근을 허용해요. my_config의 값은 ./my_config.txt 파일의 내용으로 설정되고, my_other_config는 외부 리소스로 정의되는데, 이는 플랫폼에 이미 정의되어 있다는 뜻이에요. 외부 config가 존재하지 않으면 배포가 실패해요.

services:
  redis:
    image: redis:latest
    configs:
      - my_config
      - my_other_config
configs:
  my_config:
    file: ./my_config.txt
  my_other_config:
    external: true

긴 구문 (Long syntax)

긴 구문은 서비스 작업 컨테이너 안에서 config가 어떻게 생성되는지 더 세밀하게 제어해요.

source: 플랫폼에 존재하는 config의 이름.
target: 서비스 작업 컨테이너에 마운트할 파일의 경로와 이름. 지정하지 않으면 /<source>가 기본값이에요.
uid, gid: 서비스 작업 컨테이너 안에서 마운트된 config 파일을 소유하는 숫자 uid/gid.
mode: 서비스 작업 컨테이너 안에서 마운트된 파일의 권한, 8진수 표기. 기본값은 전 세계 읽기 권한(0444)이에요. 쓰기 비트는 무시해야 해요. 실행 비트는 설정될 수 있어요.

다음 예시는 컨테이너 안의 my_config 이름을 redis_config로 설정하고, mode를 0440(그룹 읽기)으로 설정하며 사용자와 그룹을 103으로 설정해요. redis 서비스는 my_other_config config에 접근할 수 없어요.

services:
  redis:
    image: redis:latest
    configs:
      - source: my_config
        target: /redis_config
        uid: "103"
        gid: "103"
        mode: 0440
configs:
  my_config:
    external: true
  my_other_config:
    external: true

`container_name`

container_name은 기본 생성 이름 대신 사용자 지정 컨테이너 이름을 지정하는 문자열이에요.

container_name: my-web-container

Compose 파일이 container_name을 지정하면 Compose는 서비스를 하나 이상의 컨테이너로 확장하지 않아요. 그렇게 시도하면 오류가 발생해요.

container_name은 [a-zA-Z0-9][a-zA-Z0-9_.-]+의 정규식 형식을 따라요.

`credential_spec`

credential_spec은 관리형 서비스 계정의 자격 증명 스펙을 구성해요.

Windows 컨테이너를 사용하는 서비스가 있으면 credential_spec에 file:과 registry: 프로토콜을 사용할 수 있어요. Compose는 사용자 지정 사용 사례를 위한 추가 프로토콜도 지원해요.

credential_spec은 file://<filename> 또는 registry://<value-name> 형식이어야 해요.

credential_spec:
  file: my-credential-spec.json

registry:를 사용하면 자격 증명 스펙은 데몬 호스트의 Windows 레지스트리에서 읽혀요. 주어진 이름의 레지스트리 값은 다음 위치에 있어야 해요.

HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs

다음 예시는 레지스트리에서 my-credential-spec이라는 값에서 자격 증명 스펙을 로드해요.

credential_spec:
  registry: my-credential-spec

gMSA 구성 예시

서비스에 대한 gMSA 자격 증명 스펙을 구성할 때는 다음 예시처럼 config와 함께 자격 증명 스펙만 지정하면 돼요.

services:
  myservice:
    image: myimage:latest
    credential_spec:
      config: my_credential_spec

configs:
  my_credentials_spec:
    file: ./my-credential-spec.json

`depends_on`

depends_on 속성으로 서비스 시작·종료 순서를 제어할 수 있어요. 서비스가 긴밀하게 결합되어 있고 시작 순서가 애플리케이션 기능에 영향을 준다면 유용해요.

짧은 구문 (Short syntax)

짧은 구문 변형은 의존성의 서비스 이름만 지정해요. 서비스 의존성은 다음 동작을 일으켜요.

Compose는 의존성 순서로 서비스를 생성해요. 다음 예시에서 db와 redis는 web보다 먼저 생성돼요.
Compose는 의존성 순서로 서비스를 제거해요. 다음 예시에서 web은 db와 redis보다 먼저 제거돼요.

간단한 예시:

services:
  web:
    build: .
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres:18

Compose는 의존 서비스를 시작하기 전에 의존 서비스가 시작되었음을 보장해요. 짧은 구문에서는 Compose는 의존 서비스가 "healthy"가 될 때까지 기다리지 않아요.

긴 구문 (Long syntax)

긴 형식 구문은 짧은 형식으로 표현할 수 없는 추가 필드의 구성을 활성화해요.

restart: true로 설정하면 Compose는 의존 서비스 업데이트 후 이 서비스를 재시작해요. 이는 Compose 작업이 제어하는 명시적 재시작에 적용되며, 컨테이너가 죽은 후 컨테이너 런타임에 의한 자동 재시작은 제외돼요. Docker Compose 2.17.0 버전에서 도입됐어요.
condition: 의존성이 충족된 것으로 간주되는 조건을 설정해요.
- service_started: 앞서 설명한 짧은 구문과 동등.
- service_healthy: 의존 서비스를 시작하기 전에 의존성이 "healthy"일 것으로 예상됨을 지정 ( healthcheck로 표시).
- service_completed_successfully: 의존 서비스를 시작하기 전에 의존성이 성공적으로 완료되어 실행될 것으로 예상됨을 지정.
required: false로 설정하면 Compose는 의존 서비스가 시작되지 않거나 사용 불가할 때 경고만 해요. 정의하지 않으면 required의 기본값은 true예요. Docker Compose 2.20.0 버전에서 도입됐어요.

서비스 의존성은 다음 동작을 일으켜요.

Compose는 의존성 순서로 서비스를 생성해요. 다음 예시에서 db와 redis는 web보다 먼저 생성돼요.
Compose는 service_healthy로 표시된 의존성의 healthcheck 통과를 기다려요. 다음 예시에서 web이 생성되기 전에 db가 "healthy"일 것으로 예상돼요.
Compose는 의존성 순서로 서비스를 제거해요. 다음 예시에서 web은 db와 redis보다 먼저 제거돼요.

services:
  web:
    build: .
    depends_on:
      db:
        condition: service_healthy
        restart: true
      redis:
        condition: service_started
  redis:
    image: redis
  db:
    image: postgres:18

Compose는 의존 서비스를 시작하기 전에 의존 서비스가 시작되었음을 보장해요. 또한 service_healthy로 표시된 의존 서비스가 시작되기 전에 "healthy"임을 보장해요.

`deploy`

deploy는 Compose Deploy Specification에 정의된 대로 서비스의 배포와 수명 주기 구성을 지정해요.

`develop`

develop는 Development Section에 정의된 대로 컨테이너를 소스와 동기화 상태로 유지하기 위한 개발 구성을 지정해요.

`device_cgroup_rules`

device_cgroup_rules는 이 컨테이너에 대한 디바이스 cgroup 규칙 목록을 정의해요. 형식은 Linux 커널이 Control Groups Device Whitelist Controller에 지정한 형식과 동일해요.

device_cgroup_rules:
  - 'c 1:3 mr'
  - 'a 7:* rmw'

`devices`

devices는 생성된 컨테이너에 대한 디바이스 매핑 목록을 HOST_PATH:CONTAINER_PATH[:CGROUP_PERMISSIONS] 형식으로 정의해요.

devices:
  - "/dev/ttyUSB0:/dev/ttyUSB0"
  - "/dev/sda:/dev/xvda:rwm"

devices는 CDI 구문에 의존해 컨테이너 런타임이 디바이스를 선택하게 할 수도 있어요.

devices:
  - "vendor1.com/device=gpu"

`dns`

dns는 컨테이너 네트워크 인터페이스 구성에 설정할 사용자 지정 DNS 서버를 정의해요. 단일 값이거나 목록일 수 있어요.

dns: 8.8.8.8

dns:
  - 8.8.8.8
  - 9.9.9.9

`dns_opt`

dns_opt는 컨테이너의 DNS 리졸버(Linux의 /etc/resolv.conf 파일)에 전달할 사용자 지정 DNS 옵션을 나열해요.

dns_opt:
  - use-vc
  - no-tld-query

`dns_search`

dns_search는 컨테이너 네트워크 인터페이스 구성에 설정할 사용자 지정 DNS 검색 도메인을 정의해요. 단일 값이거나 목록일 수 있어요.

dns_search: example.com

dns_search:
  - dc1.example.com
  - dc2.example.com

`domainname`

domainname은 서비스 컨테이너에 사용할 사용자 지정 도메인 이름을 선언해요. 유효한 RFC 1123 호스트 이름이어야 해요.

`driver_opts`

driver_opts는 드라이버에 전달할 옵션을 키-값 쌍 목록으로 지정해요. 이 옵션은 드라이버에 따라 달라요.

services:
  app:
    networks:
      app_net:
        driver_opts:
          com.docker.network.bridge.host_binding_ipv4: "127.0.0.1"

자세한 내용은 네트워크 드라이버 문서를 참고하세요.

`entrypoint`

entrypoint는 서비스 컨테이너의 기본 entrypoint를 선언해요. 서비스의 Dockerfile에 있는 ENTRYPOINT 명령을 재정의해요.

entrypoint가 null이 아니면 Compose는 이미지의 기본 명령(예: Dockerfile의 CMD 명령)을 무시해요.

entrypoint 프로세스가 실행할 기본 명령을 설정하거나 재정의하려면 command도 참고하세요.

짧은 형식에서는 값을 문자열로 정의할 수 있어요.

entrypoint: /code/entrypoint.sh

대안으로 값은 Dockerfile과 유사한 방식으로 목록일 수도 있어요.

entrypoint:
  - php
  - -d
  - zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so
  - -d
  - memory_limit=-1
  - vendor/bin/phpunit

값이 null이면 이미지의 기본 entrypoint가 사용돼요.

값이 [](빈 목록) 또는 ''(빈 문자열)이면 이미지가 선언한 기본 entrypoint는 무시되거나, 다시 말해 비어 있도록 재정의돼요.

`env_file`

env_file 속성은 컨테이너에 전달할 환경 변수를 담은 파일을 하나 이상 지정하는 데 사용해요.

env_file: .env

상대 경로는 Compose 파일의 상위 폴더에서 해석돼요. 절대 경로는 Compose 파일을 이식 불가능하게 만들기 때문에 env_file을 설정하는 데 그런 경로를 사용하면 Compose가 경고해요.

environment 섹션에 선언된 환경 변수는 이 값들을 재정의해요. 그 값들이 비어 있거나 정의되지 않았더라도 마찬가지예요.

env_file은 목록일 수도 있어요. 목록의 파일은 위에서 아래로 처리돼요. 두 환경 파일에서 같은 변수가 지정되면 목록의 마지막 파일 값이 우선해요.

env_file:
  - ./a.env
  - ./b.env

목록 요소는 매핑으로도 선언할 수 있는데, 그러면 추가 속성을 설정할 수 있어요.

`required`

required 속성은 기본적으로 true예요. required가 false로 설정되고 .env 파일이 없으면 Compose는 항목을 조용히 무시해요.

env_file:
  - path: ./default.env
    required: true # default
  - path: ./override.env
    required: false

`format`

format 속성은 env_file에 대체 파일 형식을 사용하게 해 줘요. 설정하지 않으면 env_file은 Env_file 형식에 설명된 Compose 규칙에 따라 파싱돼요.

raw 형식은 key=value 항목이 있는 env_file을 Compose가 보간을 위해 값을 파싱하려 시도하지 않고 사용하게 해 줘요. 이를 통해 따옴표와 $ 부호를 포함한 값을 그대로 전달할 수 있어요.

env_file:
  - path: ./default.env
    format: raw

`Env_file` 형식

.env 파일의 각 줄은 VAR[=[VAL]] 형식이어야 해요. 다음 구문 규칙이 적용돼요.

#로 시작하는 줄은 주석으로 처리되고 무시돼요.
빈 줄은 무시돼요.
따옴표 없음·이중 따옴표(") 값은 보간(Interpolation)이 적용돼요.
각 줄은 키-값 쌍을 나타내요. 값은 선택적으로 따옴표로 묶을 수 있어요.
키와 값을 구분하는 구분자는 = 또는 :일 수 있어요.
값 앞·뒤 공백은 무시돼요.
- VAR=VAL -> VAL
- VAR="VAL" -> VAL
- VAR='VAL' -> VAL
- VAR: VAL -> VAL
- VAR = VAL -> VAL
따옴표 없는 값의 인라인 주석은 공백이 앞에 있어야 해요.
- VAR=VAL # comment -> VAL
- VAR=VAL# not a comment -> VAL# not a comment
따옴표 있는 값의 인라인 주석은 닫는 따옴표 뒤에 와야 해요.
- VAR="VAL # not a comment" -> VAL # not a comment
- VAR="VAL" # comment -> VAL
단일 따옴표(') 값은 그대로 사용돼요.
- VAR='$OTHER' -> $OTHER
- VAR='${OTHER}' -> ${OTHER}
따옴표는 \로 이스케이프할 수 있어요.
- VAR='Let\'s go!' -> Let's go!
- VAR="{\"hello\": \"json\"}" -> {"hello": "json"}
\n, \r, \t, \\를 포함한 일반적인 셸 이스케이프 시퀀스는 이중 따옴표 값에서 지원돼요.
- VAR="some\tvalue" -> some value
- VAR='some\tvalue' -> some\tvalue
- VAR=some\tvalue -> some\tvalue

VAL은 생략될 수 있으며, 그 경우 변수 값은 빈 문자열이에요. =VAL은 생략될 수 있으며, 그 경우 변수는 설정되지 않아요.

# Set Rails/Rack environment
RACK_ENV=development
VAR="quoted"

`environment`

environment 속성은 컨테이너에 설정된 환경 변수를 정의해요. environment는 배열이나 맵을 사용할 수 있어요. true, false, yes, no 같은 불리언 값은 YAML 파서가 True나 False로 변환하지 않도록 따옴표로 묶어야 해요.

환경 변수는 단일 키로 선언될 수 있어요 (등호 없는 값). 이 경우 Compose는 값을 해석하는 것을 사용자에게 맡겨요. 값이 해석되지 않으면 변수는 설정되지 않고 서비스 컨테이너 환경에서 제거돼요.

맵 구문:

environment:
  RACK_ENV: development
  SHOW: "true"
  USER_INPUT:

배열 구문:

environment:
  - RACK_ENV=development
  - SHOW=true
  - USER_INPUT

서비스에 env_file과 environment가 모두 설정되면 environment가 설정한 값이 우선해요.

`expose`

expose는 Compose가 컨테이너에서 노출하는 (들어오는) 포트 또는 포트 범위를 정의해요. 이 포트는 연결된 서비스에 접근 가능해야 하며 호스트 머신에 게시하면 안 돼요. 내부 컨테이너 포트만 지정할 수 있어요.

구문은 포트 범위에 대해 <portnum>/[<proto>] 또는 <startport-endport>/[<proto>]예요. 명시적으로 설정하지 않으면 tcp 프로토콜이 사용돼요.

expose:
  - "3000"
  - "8000"
  - "8080-8085/tcp"

[!NOTE]

이미지의 Dockerfile이 이미 포트를 노출하면 Compose 파일에서 expose를 설정하지 않아도 네트워크의 다른 컨테이너에 보여요.

`extends`

extends는 다른 파일이나 완전히 다른 프로젝트 사이에서 공통 구성을 공유하게 해 줘요. extends로 한 곳에서 공통 서비스 옵션 집합을 정의하고 어디서나 참조할 수 있어요. 다른 Compose 파일을 참조하고 자신의 필요에 맞게 일부 속성을 재정의하며 애플리케이션에서도 사용하려는 서비스를 선택할 수 있어요.

extends는 다른 구성 키와 함께 어떤 서비스에서도 사용할 수 있어요. extends 값은 필수 service와 선택적 file 키로 정의된 매핑이어야 해요.

extends:
  file: common.yml
  service: webapp

service: 베이스로 참조되는 서비스의 이름을 정의해요. 예: web 또는 database.
file: 그 서비스를 정의하는 Compose 구성 파일의 위치.

extends는 docker stack deploy로 배포할 때는 지원되지 않아요.

제약 (Restrictions)

서비스가 extends로 참조되면 다른 리소스에 대한 의존성을 선언할 수 있어요. 이 의존성은 volumes, networks, configs, secrets, links, volumes_from, depends_on 같은 속성으로 명시적으로 정의될 수 있어요. 대안으로 의존성은 ipc, pid 또는 network_mode 같은 네임스페이스 선언에서 service:{name} 구문으로 다른 서비스를 참조할 수 있어요.

Compose는 이 참조된 리소스를 확장된 모델로 자동 가져오지 않아요. extends에 의존하는 모델에 모든 필수 리소스를 명시적으로 선언하는 것은 사용자의 책임이에요.

extends의 순환 참조는 지원되지 않으며, 감지되면 Compose가 오류를 반환해요.

참조된 서비스 찾기

file 값은 다음과 같을 수 있어요.

존재하지 않음. 같은 Compose 파일 안의 다른 서비스가 참조되고 있음을 나타냄.
파일 경로. 다음 중 하나일 수 있어요.
- 상대 경로. 이 경로는 기본 Compose 파일의 위치를 기준으로 간주돼요.
- 절대 경로.

service로 표시된 서비스는 식별된 참조 Compose 파일에 존재해야 해요. Compose는 다음 경우에 오류를 반환해요.

service로 표시된 서비스가 없음.
file로 표시된 Compose 파일이 없음.

서비스 정의 병합

현재 Compose 파일의 기본 서비스 정의와 extends가 지정한 참조된 정의, 두 서비스 정의는 다음과 같이 병합돼요.

매핑: 기본 서비스 정의의 매핑 키는 참조된 서비스 정의의 매핑 키를 재정의해요. 재정의되지 않은 키는 그대로 포함돼요.
시퀀스: 항목은 새 시퀀스로 결합돼요. 요소 순서는 유지되며 참조된 항목이 먼저, 기본 항목이 그 다음이에요.
스칼라: 기본 서비스 정의의 키가 참조된 키보다 우선해요.

매핑

다음 키는 매핑으로 취급해야 해요: annotations, build.args, build.labels, build.extra_hosts, deploy.labels, deploy.update_config, deploy.rollback_config, deploy.restart_policy, deploy.resources.limits, environment, healthcheck, labels, logging.options, sysctls, storage_opt, extra_hosts, ulimits.

healthcheck에 적용되는 예외 하나는, 참조된 매핑도 disable: true를 지정하지 않는 한 기본 매핑이 disable: true를 지정할 수 없다는 거예요. 이 경우 Compose는 오류를 반환해요. 예를 들어 다음 입력:

services:
  common:
    image: busybox
    environment:
      TZ: utc
      PORT: 80
  cli:
    extends:
      service: common
    environment:
      PORT: 8080

cli 서비스에 대해 다음 구성을 만든다. 배열 구문을 사용해도 같은 출력이 만들어져요.

environment:
  PORT: 8080
  TZ: utc
image: busybox

blkio_config.device_read_bps, blkio_config.device_read_iops, blkio_config.device_write_bps, blkio_config.device_write_iops, devices, volumes 아래 항목도 키가 컨테이너 안의 대상 경로인 매핑으로 취급돼요.

예를 들어 다음 입력:

services:
  common:
    image: busybox
    volumes:
      - common-volume:/var/lib/backup/data:rw
  cli:
    extends:
      service: common
    volumes:
      - cli-volume:/var/lib/backup/data:ro

cli 서비스에 대해 다음 구성을 만든다. 이제 마운트된 경로가 새 볼륨 이름을 가리키고 ro 플래그가 적용됐음을 주목하세요.

image: busybox
volumes:
- cli-volume:/var/lib/backup/data:ro

참조된 서비스 정의에 extends 매핑이 포함되어 있으면 그 아래 항목은 새 병합 정의로 그냥 복사돼요. 그런 다음 extends 키가 남지 않을 때까지 병합 과정이 다시 시작돼요.

예를 들어 다음 입력:

services:
  base:
    image: busybox
    user: root
  common:
    image: busybox
    extends:
      service: base
  cli:
    extends:
      service: common

cli 서비스에 대해 다음 구성을 만든다. 여기서 cli 서비스는 common 서비스에서 user 키를 얻고, common은 다시 base 서비스에서 이 키를 얻어요.

image: busybox
user: root

시퀀스

다음 키는 시퀀스로 취급해야 해요: cap_add, cap_drop, configs, deploy.placement.constraints, deploy.placement.preferences, deploy.reservations.generic_resources, device_cgroup_rules, expose, external_links, ports, secrets, security_opt. 병합으로 생긴 중복은 시퀀스가 고유 요소만 포함하도록 제거돼요.

예를 들어 다음 입력:

services:
  common:
    image: busybox
    security_opt:
      - label=role:ROLE
  cli:
    extends:
      service: common
    security_opt:
      - label=user:USER

cli 서비스에 대해 다음 구성을 만든다.

image: busybox
security_opt:
- label=role:ROLE
- label=user:USER

목록 구문을 사용하면 다음 키도 시퀀스로 취급해야 해요: dns, dns_search, env_file, tmpfs. 앞서 언급한 시퀀스 필드와 달리 병합으로 생긴 중복은 제거되지 않아요.

스칼라

서비스 정의의 다른 허용된 키는 스칼라로 취급해야 해요.

`external_links`

external_links는 서비스 컨테이너를 Compose 애플리케이션 밖에서 관리되는 서비스에 연결해요. external_links는 플랫폼 조회 메커니즘으로 가져올 기존 서비스의 이름을 정의해요. SERVICE:ALIAS 형식의 별칭을 지정할 수 있어요.

external_links:
  - redis
  - database:mysql
  - database:postgresql

`extra_hosts`

extra_hosts는 컨테이너 네트워크 인터페이스 구성(Linux의 /etc/hosts)에 호스트 이름 매핑을 추가해요.

짧은 구문 (Short syntax)

짧은 구문은 목록의 일반 문자열을 사용해요. 값은 HOSTNAME=IP 형식으로 추가 호스트의 호스트 이름과 IP 주소를 설정해야 해요.

extra_hosts:
  - "somehost=162.242.195.82"
  - "otherhost=50.31.209.229"
  - "myhostv6=::1"

IPv6 주소는 대괄호로 묶을 수 있어요. 예를 들면:

extra_hosts:
  - "myhostv6=[::1]"

구분자는 =가 선호되지만 :도 사용할 수 있어요. Docker Compose 2.24.1 버전에서 도입됐어요. 예를 들면:

extra_hosts:
  - "somehost:162.242.195.82"
  - "myhostv6:::1"

긴 구문 (Long syntax)

대안으로 extra_hosts는 호스트 이름과 IP 사이의 매핑으로 설정할 수 있어요.

extra_hosts:
  somehost: "162.242.195.82"
  otherhost: "50.31.209.229"
  myhostv6: "::1"

Compose는 컨테이너의 네트워크 구성에 IP 주소와 호스트 이름으로 짝을 이루는 항목을 만들어요. 즉 Linux에서는 /etc/hosts에 추가 줄이 생겨요.

162.242.195.82  somehost
50.31.209.229   otherhost
::1             myhostv6

`gpus`

gpus는 컨테이너 사용을 위해 할당할 GPU 디바이스를 지정해요. 암시적 gpu capability가 있는 디바이스 요청(device request)과 동등해요.

services:
  model:
    gpus:
      - driver: 3dfx
        count: 2

gpus는 문자열 all로 설정해 사용 가능한 모든 GPU 디바이스를 컨테이너에 할당할 수도 있어요.

services:
  model:
    gpus: all

`group_add`

group_add는 컨테이너 안의 사용자가 반드시 구성원이어야 하는 추가 그룹을 이름이나 번호로 지정해요.

이것이 유용한 예는 (다른 사용자로 실행되는) 여러 컨테이너가 공유 볼륨의 같은 파일을 모두 읽거나 써야 할 때예요. 그 파일은 모든 컨테이너가 공유하는 그룹이 소유할 수 있고, group_add로 지정할 수 있어요.

services:
  myservice:
    image: alpine
    group_add:
      - mail

생성된 컨테이너 안에서 id를 실행하면 사용자가 mail 그룹에 속한 것으로 보여야 하는데, group_add를 선언하지 않았다면 그렇지 않았을 거예요.

`healthcheck`

healthcheck 속성은 서비스 컨테이너가 "healthy"인지 결정하기 위해 실행되는 검사를 선언해요. 서비스의 Docker 이미지가 설정한 HEALTHCHECK Dockerfile 명령과 같은 방식으로 동작하고 같은 기본값을 가져요. Compose 파일은 Dockerfile에 설정된 값을 재정의할 수 있어요.

HEALTHCHECK에 대한 자세한 내용은 Dockerfile 참조를 참고하세요.

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost"]
  interval: 1m30s
  timeout: 10s
  retries: 3
  start_period: 40s
  start_interval: 5s

interval, timeout, start_period, start_interval은 duration(기간)으로 지정돼요. Docker Compose 2.20.2 버전에서 도입됐어요.

test는 Compose가 컨테이너 상태를 확인하기 위해 실행하는 명령을 정의해요. 문자열이나 목록일 수 있어요. 목록이라면 첫 항목은 NONE, CMD 또는 CMD-SHELL 중 하나여야 해요. 문자열이라면 그 뒤에 CMD-SHELL을 지정한 것과 동등해요.

# 로컬 웹 앱에 접근 (Hit the local web app)
test: ["CMD", "curl", "-f", "http://localhost"]

CMD-SHELL을 사용하면 컨테이너의 기본 셸(Linux /bin/sh)로 구성된 명령을 문자열로 실행해요. 두 형식 모두 동등해요.

test: ["CMD-SHELL", "curl -f http://localhost || exit 1"]

test: curl -f https://localhost || exit 1

NONE은 healthcheck를 비활성화하며, 서비스의 Docker 이미지가 설정한 Healthcheck Dockerfile 명령을 비활성화하는 데 주로 유용해요. 대안으로 이미지가 설정한 healthcheck는 disable: true로 비활성화할 수 있어요.

healthcheck:
  disable: true

`hostname`

hostname은 서비스 컨테이너에 사용할 사용자 지정 호스트 이름을 선언해요. 유효한 RFC 1123 호스트 이름이어야 해요.

`image`

image는 컨테이너를 시작할 이미지를 지정해요. image는 addressable image format을 따라야 해요: [<registry>/][<project>/]<image>[:<tag>|@<digest>].

    image: redis
    image: redis:5
    image: redis@sha256:0ed5d5928d4737458944eb604cc8509e245c3e19d02ad83935398bc4b991aac7
    image: library/redis
    image: docker.io/library/redis
    image: my_private.registry:5000/redis

플랫폼에 이미지가 없으면 Compose는 pull_policy에 따라 이미지를 pull하려 시도해요. Compose Build Specification도 사용한다면 소스에서 이미지를 빌드하는 것보다 pull의 우선순위를 제어하는 대체 옵션이 있지만, 이미지 pull이 기본 동작이에요.

build 섹션이 선언되어 있으면 Compose 파일에서 image는 생략될 수 있어요. Compose Build Specification을 사용하지 않는다면 Compose 파일에서 image가 없으면 Compose는 동작하지 않아요.

`init`

init은 컨테이너 안에서 시그널을 전달하고 프로세스를 거두는(수거하는) init 프로세스(PID 1)를 실행해요. 서비스에 이 기능을 활성화하려면 이 옵션을 true로 설정하세요.

services:
  web:
    image: alpine:latest
    init: true

사용되는 init 바이너리는 플랫폼별이에요.

`ipc`

ipc는 서비스 컨테이너가 설정한 IPC 격리 모드를 구성해요.

shareable: 컨테이너에 자체 전용 IPC 네임스페이스를 부여하며, 다른 컨테이너와 공유할 가능성이 있어요.
service:{name}: 컨테이너가 다른 컨테이너의 (shareable) IPC 네임스페이스에 참여하게 함.

    ipc: "shareable"
    ipc: "service:[service name]"

`isolation`

isolation은 컨테이너의 격리 기술을 지정해요. 지원되는 값은 플랫폼별이에요.

`labels`

labels는 컨테이너에 메타데이터를 추가해요. 배열이나 맵을 사용할 수 있어요.

라벨이 다른 소프트웨어가 사용하는 라벨과 충돌하지 않도록 역 DNS 표기법을 사용하는 것이 좋아요.

labels:
  com.example.description: "Accounting webapp"
  com.example.department: "Finance"
  com.example.label-with-empty-value: ""

labels:
  - "com.example.description=Accounting webapp"
  - "com.example.department=Finance"
  - "com.example.label-with-empty-value"

Compose는 정규 라벨로 컨테이너를 만들어요.

com.docker.compose.project: Compose가 만든 모든 리소스에 사용자 프로젝트 이름으로 설정됨.
com.docker.compose.service: Compose 파일에 정의된 대로 서비스 이름으로 서비스 컨테이너에 설정됨.

com.docker.compose 라벨 접두사는 예약되어 있어요. Compose 파일에서 이 접두사로 라벨을 지정하면 런타임 오류가 발생해요.

`label_file`

label_file 속성은 외부 파일이나 파일 목록에서 서비스의 라벨을 로드하게 해 줘요. Compose 파일을 어지럽히지 않고 여러 라벨을 관리하는 편리한 방법을 제공해요.

파일은 env_file과 유사한 키-값 형식을 사용해요. 목록으로 여러 파일을 지정할 수 있어요. 여러 파일을 사용하면 목록에 나타나는 순서대로 처리돼요. 다른 파일에서 같은 라벨이 정의되면 목록의 마지막 파일 값이 이전 것을 재정의해요.

services:
  one:
    label_file: ./app.labels

  two:
    label_file:
      - ./app.labels
      - ./additional.labels

라벨이 label_file과 labels 속성 둘 다에 정의되면 labels의 값이 우선해요.

`links`

links는 다른 서비스의 컨테이너에 대한 네트워크 링크를 정의해요. 서비스 이름과 링크 별칭(SERVICE:ALIAS)을 둘 다 지정하거나 서비스 이름만 지정해요.

web:
  links:
    - db
    - db:database
    - redis

연결된 서비스의 컨테이너는 별칭과 동일한 호스트 이름으로 접근 가능하며, 별칭이 지정되지 않았다면 서비스 이름으로 접근해요.

서비스가 통신하도록 links는 필요하지 않아요. 특정 네트워크 구성이 설정되지 않으면 어떤 서비스든 default 네트워크에서 해당 서비스 이름으로 다른 서비스에 도달할 수 있어요. 서비스가 연결된 네트워크를 지정하면 links는 네트워크 구성을 재정의하지 않아요. 공유 네트워크에 연결되지 않은 서비스는 서로 통신할 수 없어요. Compose는 구성 불일치에 대해 경고하지 않아요.

links는 depends_on과 같은 방식으로 서비스 간 암시적 의존성도 표현하므로 서비스 시작 순서를 결정해요.

`logging`

logging은 서비스의 로깅 구성을 정의해요.

logging:
  driver: syslog
  options:
    syslog-address: "tcp://192.168.0.42:123"

driver 이름은 서비스 컨테이너의 로깅 드라이버를 지정해요. 기본값과 사용 가능한 값은 플랫폼별이에요. 드라이버별 옵션은 options로 키-값 쌍으로 설정할 수 있어요.

`mac_address`

Docker Compose 버전 2.24.0 이상에서 사용 가능.

mac_address는 서비스 컨테이너에 Mac 주소를 설정해요.

[!NOTE] 컨테이너 런타임이 이 값을 거부할 수 있어요. 예를 들어 Docker Engine >= v25.0. 그 경우 networks.mac_address를 대신 사용해야 해요.

`mem_limit`

mem_limit는 컨테이너가 할당할 수 있는 메모리 양의 제한을 구성하며, byte value(바이트 값)를 표현하는 문자열로 설정돼요.

설정되면 mem_limit는 Deploy Specification의 limits.memory 속성과 일치해야 해요.

`mem_reservation`

mem_reservation은 컨테이너가 할당할 수 있는 메모리 양의 예약을 구성하며, byte value(바이트 값)를 표현하는 문자열로 설정돼요.

설정되면 mem_reservation은 Deploy Specification의 reservations.memory 속성과 일치해야 해요.

`mem_swappiness`

mem_swappiness는 백분율로 0~100 사이의 값을 정의하며, 호스트 커널이 컨테이너가 사용하는 익명 메모리 페이지를 스왑아웃할지 결정해요.

0: 익명 페이지 스와핑을 끔.
100: 모든 익명 페이지를 스왑 가능하게 설정.

기본값은 플랫폼별이에요.

`memswap_limit`

memswap_limit는 컨테이너가 디스크로 스왑할 수 있는 메모리 양을 정의해요. 이는 memory도 설정된 경우에만 의미가 있는 수정자 속성이에요. 스왑을 사용하면 컨테이너가 사용 가능한 모든 메모리를 소진했을 때 초과 메모리 요구사항을 디스크로 쓸 수 있어요. 자주 디스크로 스왑하는 애플리케이션에는 성능 패널티가 있어요.

memswap_limit가 양의 정수로 설정되면 memory와 memswap_limit 둘 다 설정해야 해요. memswap_limit은 사용 가능한 메모리와 스왑의 총량을 나타내고, memory는 비스왑 메모리가 사용하는 양을 제어해요. 그래서 memory="300m"이고 memswap_limit="1g"이면 컨테이너는 메모리 300m과 스왑 700m (1g - 300m)를 사용할 수 있어요.
memswap_limit가 0으로 설정되면 설정은 무시되고 값은 설정되지 않은 것으로 취급돼요.
memswap_limit가 memory와 같은 값으로 설정되고 memory가 양의 정수로 설정되면 컨테이너는 스왑에 접근할 수 없어요.
memswap_limit가 설정되지 않고 memory가 설정되면 호스트에 스왑 메모리가 구성되어 있다면 컨테이너는 memory 설정만큼의 스왑을 사용할 수 있어요. 예를 들어 memory="300m"이고 memswap_limit이 설정되지 않으면 컨테이너는 메모리와 스왑을 합쳐 총 600m을 사용할 수 있어요.
memswap_limit가 명시적으로 -1로 설정되면 컨테이너는 호스트 시스템에서 사용 가능한 만큼의 무제한 스왑 사용이 허용돼요.

`models`

models는 서비스가 런타임에 사용해야 하는 AI 모델을 정의해요. 참조된 각 모델은 models 최상위 요소 아래에 정의되어야 해요.

services:
  short_syntax:
    image: app
    models:
      - my_model
  long_syntax:
    image: app
    models:
      my_model:
        endpoint_var: MODEL_URL
        model_var: MODEL

서비스가 모델에 연결되면 Docker Compose는 컨테이너에 연결 세부 정보와 모델 식별자를 전달하는 환경 변수를 주입해요. 이를 통해 애플리케이션이 값을 하드코딩하지 않고 런타임에 동적으로 모델을 찾고 통신할 수 있어요.

긴 구문 (Long syntax)

긴 구문은 환경 변수 이름을 더 제어하게 해 줘요.

endpoint_var는 모델 러너의 URL을 담는 환경 변수 이름을 설정해요.
model_var는 모델 식별자를 담는 환경 변수 이름을 설정해요.

둘 중 하나가 생략되면 Compose는 다음 규칙으로 모델 키에 기반해 환경 변수 이름을 자동 생성해요.

모델 키를 대문자로 변환
- 문자를 _로 바꿈
엔드포인트 변수에 _URL 추가

`network_mode`

network_mode는 서비스 컨테이너의 네트워크 모드를 설정해요.

bridge: 컨테이너를 프로젝트 특정 네트워크 대신 Docker의 기본 bridge 네트워크에 연결. 기본 bridge 네트워크의 컨테이너는 서비스 이름으로 서로를 해석할 수 없어요. DNS 해석에는 사용자 정의 네트워크를 대신 사용하세요.
none: 모든 컨테이너 네트워킹을 끔.
host: 컨테이너에 호스트의 네트워크 인터페이스에 대한 원시 접근을 부여.
service:{name}: 서비스 이름을 참조해 지정된 컨테이너에 접근을 부여.
container:{name}: 컨테이너 ID를 참조해 지정된 컨테이너에 접근을 부여.

컨테이너 네트워크에 대한 자세한 내용은 Docker Engine 문서를 참고하세요.

    network_mode: "bridge"
    network_mode: "host"
    network_mode: "none"
    network_mode: "service:[service name]"

설정되면 networks 속성은 허용되지 않으며 Compose는 두 속성을 모두 포함한 Compose 파일을 거부해요.

`networks`

networks 속성은 서비스 컨테이너가 연결된 네트워크를 정의하며, networks 최상위 요소 아래의 항목을 참조해요. networks 속성은 컨테이너의 네트워킹 측면을 관리하는 데 도움을 주며, Docker 환경 안에서 서비스가 어떻게 분할되고 상호작용하는지 제어할 수 있게 해 줘요. 이는 그 서비스의 컨테이너가 연결할 네트워크를 지정하는 데 사용돼요. 컨테이너가 서로 그리고 외부와 통신하는 방식을 정의하는 데 중요해요.

services:
  some-service:
    networks:
      - some-network
      - other-network

networks 최상위 요소에 대한 자세한 내용은 네트워크(Networks)를 참고하세요.

암시적 기본 네트워크 (Implicit default network)

Compose 파일에서 networks가 비어 있거나 없으면 Compose는 서비스가 default 네트워크에 연결된 암시적 정의를 고려해요.

services:
  some-service:
    image: foo

이 예시는 실제로 다음과 같아요.

services:
  some-service:
    image: foo
    networks:
      default: {}

서비스가 네트워크에 연결되지 않게 하려면 network_mode: none을 설정해야 해요.

`aliases`

aliases는 네트워크에서 서비스의 대체 호스트 이름을 선언해요. 같은 네트워크의 다른 컨테이너는 서비스 이름이나 별칭을 사용해 서비스 컨테이너 중 하나에 연결할 수 있어요.

aliases는 네트워크 범위이므로 같은 서비스가 다른 네트워크에서 다른 별칭을 가질 수 있어요.

[!NOTE] 네트워크 전체 별칭은 여러 컨테이너, 심지어 여러 서비스가 공유할 수 있어요. 그렇다면 이름이 정확히 어떤 컨테이너로 해석되는지는 보장되지 않아요.

services:
  some-service:
    networks:
      some-network:
        aliases:
          - alias1
          - alias3
      other-network:
        aliases:
          - alias2

다음 예시에서 frontend 서비스는 back-tier 네트워크의 호스트 이름 backend 또는 database에서 backend 서비스에 도달할 수 있어요. monitoring 서비스는 admin 네트워크의 backend 또는 mysql에서 같은 backend 서비스에 도달할 수 있어요.

services:
  frontend:
    image: example/webapp
    networks:
      - front-tier
      - back-tier

  monitoring:
    image: example/monitoring
    networks:
      - admin

  backend:
    image: example/backend
    networks:
      back-tier:
        aliases:
          - database
      admin:
        aliases:
          - mysql

networks:
  front-tier: {}
  back-tier: {}
  admin: {}

`interface_name`

interface_name은 서비스를 주어진 네트워크에 연결하는 데 사용되는 네트워크 인터페이스의 이름을 지정하게 해 줘요. 이는 서비스와 네트워크에 걸쳐 일관되고 예측 가능한 인터페이스 이름을 보장해요.

services:
  backend:
    image: alpine
    command: ip link show
    networks:
      back-tier:
        interface_name: eth0

예시 Compose 애플리케이션을 실행하면 다음이 보여요.

backend-1  | 11: eth0@if64: <BROADCAST,MULTICAST,UP,LOWER_UP,M-DOWN> mtu 1500 qdisc noqueue state UP

`ipv4_address`, `ipv6_address`

네트워크에 참여할 때 서비스 컨테이너에 정적 IP 주소를 지정해요.

최상위 networks 섹션의 해당 네트워크 구성은 각 정적 주소를 포함하는 ipam 속성과 서브넷 구성을 가져야 해요.

services:
  frontend:
    image: example/webapp
    networks:
      front-tier:
        ipv4_address: 172.16.238.10
        ipv6_address: 2001:3984:3989::10

networks:
  front-tier:
    ipam:
      driver: default
      config:
        - subnet: "172.16.238.0/24"
        - subnet: "2001:3984:3989::/64"

`link_local_ips`

link_local_ips는 링크-로컬 IP 목록을 지정해요. 링크-로컬 IP는 잘 알려진 서브넷에 속하는 특수 IP이며 순전히 운영자가 관리하고, 일반적으로 배포된 아키텍처에 따라 달라요.

예시:

services:
  app:
    image: busybox
    command: top
    networks:
      app_net:
        link_local_ips:
          - 57.123.22.11
          - 57.123.22.13
networks:
  app_net:
    driver: bridge

`mac_address`

mac_address는 서비스 컨테이너가 이 특정 네트워크에 연결할 때 사용하는 Mac 주소를 설정해요.

`driver_opts`

driver_opts는 드라이버에 전달할 옵션을 키-값 쌍 목록으로 지정해요. 이 옵션은 드라이버에 따라 달라요. 자세한 내용은 드라이버 문서를 참고하세요.

services:
  app:
    networks:
      app_net:
        driver_opts:
          foo: "bar"
          baz: 1

`gw_priority`

가장 높은 gw_priority를 가진 네트워크가 서비스 컨테이너의 기본 게이트웨이로 선택돼요. 지정하지 않으면 기본값은 0이에요.

다음 예시에서 app_net_2가 기본 게이트웨이로 선택될 거예요.

services:
  app:
    image: busybox
    command: top
    networks:
      app_net_1:
      app_net_2:
        gw_priority: 1
      app_net_3:
networks:
  app_net_1:
  app_net_2:
  app_net_3:

`priority`

priority는 Compose가 서비스의 컨테이너를 네트워크에 연결하는 순서를 나타내요. 지정하지 않으면 기본값은 0이에요.

컨테이너 런타임이 서비스 수준의 mac_address 속성을 받아들이면 가장 높은 priority를 가진 네트워크에 적용돼요. 그렇지 않으면 networks.mac_address 속성을 사용하세요.

priority는 어떤 네트워크가 기본 게이트웨이로 선택될지에는 영향을 주지 않아요. gw_priority 속성을 대신 사용하세요.

priority는 네트워크 연결이 컨테이너에 추가되는 순서를 제어하지 않으며, 컨테이너 안의 디바이스 이름(eth0 등)을 결정하는 데는 사용할 수 없어요.

services:
  app:
    image: busybox
    command: top
    networks:
      app_net_1:
        priority: 1000
      app_net_2:

      app_net_3:
        priority: 100
networks:
  app_net_1:
  app_net_2:
  app_net_3:

`oom_kill_disable`

oom_kill_disable이 설정되면 Compose는 메모리 부족 시 컨테이너를 죽이지 않도록 플랫폼을 구성해요.

`oom_score_adj`

oom_score_adj는 메모리 부족 시 플랫폼이 컨테이너를 죽이는 선호도를 조정해요. 값은 -1000, 1000 범위 안에 있어야 해요.

`pid`

pid는 Compose가 만든 컨테이너의 PID 모드를 설정해요. 지원되는 값은 플랫폼별이에요.

`pids_limit`

pids_limit는 컨테이너의 PIDs 제한을 조정해요. 무제한 PIDs로 설정하려면 -1로 설정하세요.

pids_limit: 10

설정되면 pids_limit는 Deploy Specification의 pids 속성과 일치해야 해요.

`platform`

platform은 서비스 컨테이너가 실행되는 대상 플랫폼을 정의해요. os[/arch[/variant]] 구문을 사용해요.

os, arch, variant의 값은 OCI Image Spec이 사용하는 관례를 따라야 해요.

Compose는 이 속성을 사용해 이미지의 어떤 버전이 pull될지 또는/그리고 서비스 빌드가 어떤 플랫폼에서 수행될지 결정해요.

platform: darwin
platform: windows/amd64
platform: linux/arm64/v8

`ports`

ports는 호스트 머신과 컨테이너 사이의 포트 매핑을 정의하는 데 사용돼요. 이는 컨테이너 안에서 실행되는 서비스에 외부 접근을 허용하는 데 중요해요. 간단한 포트 매핑용 짧은 구문이나, 프로토콜 유형·네트워크 모드 같은 추가 옵션을 포함하는 긴 구문으로 정의할 수 있어요.

[!NOTE]

포트 매핑은 network_mode: host와 함께 사용하면 안 돼요. 그렇게 하면 network_mode: host가 이미 컨테이너 포트를 호스트 네트워크에 직접 노출하므로 포트 매핑이 필요 없어서 런타임 오류가 발생해요.

짧은 구문 (Short syntax)

짧은 구문은 콜론으로 구분된 문자열로 호스트 IP, 호스트 포트, 컨테이너 포트를 다음 형식으로 설정해요.

[HOST:]CONTAINER[/PROTOCOL] 여기서:

HOST는 [IP:](port | range) (선택). 설정하지 않으면 모든 네트워크 인터페이스(0.0.0.0)에 바인딩.
CONTAINER는 port | range.
PROTOCOL은 포트를 지정된 프로토콜 tcp 또는 udp로 제한 (선택). 기본값은 tcp.

[!WARNING]

호스트 IP(예: 127.0.0.1)를 지정하지 않으면 Docker는 모든 인터페이스(0.0.0.0)에 바인딩하여 호스트 방화벽 규칙을 우회해요. 호스트에 공개 IP가 있으면 이를 통해 컨테이너가 인터넷에 직접 노출될 수 있어요. 자세한 내용은 포트 게시·매핑을 참고하세요.

포트는 단일 값이거나 범위일 수 있어요. HOST와 CONTAINER는 동등한 범위를 사용해야 해요.

두 포트를 모두(HOST:CONTAINER) 지정하거나 컨테이너 포트만 지정할 수 있어요. 후자의 경우 컨테이너 런타임이 호스트의 할당되지 않은 포트를 자동으로 할당해요.

HOST:CONTAINER는 항상 (따옴표 있는) 문자열로 지정해야 해요. YAML base-60 float와의 충돌을 피하려고요.

IPv6 주소는 대괄호로 묶을 수 있어요.

예시:

ports:
  - "3000"
  - "3000-3005"
  - "8000:8000"
  - "9090-9091:8080-8081"
  - "49100:22"
  - "8000-9000:80"
  - "127.0.0.1:8001:8001"
  - "127.0.0.1:5000-5010:5000-5010"
  - "::1:6000:6000"
  - "[::1]:6001:6001"
  - "6060:6060/udp"

[!NOTE]

컨테이너 엔진이 호스트 IP 매핑을 지원하지 않으면 Compose는 Compose 파일을 거부하고 지정된 호스트 IP를 무시해요.

긴 구문 (Long syntax)

긴 형식 구문은 짧은 형식으로 표현할 수 없는 추가 필드를 구성하게 해 줘요.

target: 컨테이너 포트.
published: 공개적으로 노출된 포트. 문자열로 정의되며 start-end 구문으로 범위로 설정할 수 있어요. 실제 포트는 설정된 범위 안에서 남아 있는 사용 가능한 포트가 할당된다는 뜻이에요.
host_ip: 호스트 IP 매핑. 설정하지 않으면 모든 네트워크 인터페이스(0.0.0.0)에 바인딩.
protocol: 포트 프로토콜 (tcp 또는 udp). 기본값 tcp.
app_protocol: 이 포트가 사용되는 애플리케이션 프로토콜 (TCP/IP 레벨 4 / OSI 레벨 7). 선택 사항이며, Compose가 이해하는 프로토콜에 대해 더 풍부한 동작을 제공하라는 힌트로 사용될 수 있어요. Docker Compose 2.26.0 버전에서 도입됐어요.
mode: Swarm 설정에서 포트가 게시되는 방식을 지정. host로 설정하면 Swarm의 모든 노드에 포트를 게시. ingress로 설정하면 Swarm 노드에 걸친 로드 밸런싱을 허용. 기본값 ingress.
name: 서비스 안에서 용도를 문서화하는 데 사용되는 사람이 읽을 수 있는 포트 이름.

ports:
  - name: web
    target: 80
    host_ip: 127.0.0.1
    published: "8080"
    protocol: tcp
    app_protocol: http
    mode: host

  - name: web-secured
    target: 443
    host_ip: 127.0.0.1
    published: "8083-9000"
    protocol: tcp
    app_protocol: https
    mode: host

`post_start`

post_start는 컨테이너가 시작된 후 실행할 수명 주기 훅(lifecycle hooks)의 시퀀스를 정의해요. 명령이 실행되는 정확한 시점은 보장되지 않아요.

command: 컨테이너가 시작되면 실행할 명령을 지정. 이 속성은 필수이며, 셸 형식이나 exec 형식을 사용할 수 있어요.
user: 명령을 실행할 사용자. 설정하지 않으면 기본 서비스 명령과 같은 사용자로 실행.
privileged: post_start 명령이 특권(privileged) 접근으로 실행되게 함.
working_dir: 명령을 실행할 작업 디렉토리. 설정하지 않으면 기본 서비스 명령과 같은 작업 디렉토리에서 실행.
environment: post_start 명령에 대해 특별히 환경 변수를 설정. 명령은 서비스의 기본 명령에 정의된 환경 변수를 상속하지만, 이 섹션은 새 변수를 추가하거나 기존 변수를 재정의하게 해 줘요.

services:
  test:
    post_start:
      - command: ./do_something_on_startup.sh
        user: root
        privileged: true
        environment:
          - FOO=BAR

자세한 내용은 수명 주기 훅 사용하기를 참고하세요.

pre_start

pre_start는 서비스 컨테이너가 시작되기 전에 실행할 init 컨테이너의 시퀀스를 정의해요. 각 단계는 선언된 순서대로 완료될 때까지 실행되고, 모든 단계가 0으로 종료된 후에만 서비스 컨테이너가 시작돼요. 0이 아닌 종료는 서비스와 그 의존 대상의 시작(bring-up)을 실패시켜요.

실행 중인 서비스 컨테이너 안에서 명령을 실행하는 post_start와 pre_stop과 달리, 각 pre_start 단계는 서비스 컨테이너가 생성된 후 시작되기 전에 만들어진 자체 임시(ephemeral) 컨테이너에서 실행돼요. 가능한 값은 다음과 같아요.

command: 실행할 명령. 선택한 이미지의 entrypoint가 이미 의도된 명령을 실행하면 선택 사항.
image: 임시 컨테이너에 사용될 이미지. 생략하면 부모 서비스의 이미지가 사용됨.
user: 명령을 실행할 사용자. 설정하지 않으면 image에 선언된 사용자(image 생략 시 기본 서비스 명령의 사용자)가 기본값.
privileged: pre_start 명령이 특권 접근으로 실행되게 함.
working_dir: 명령을 실행할 작업 디렉토리. 설정하지 않으면 기본 서비스 명령과 같은 작업 디렉토리에서 실행.
environment: pre_start 명령을 실행할 환경 변수를 설정. 명령은 서비스의 기본 명령에 설정된 environment를 상속하며, 이 섹션은 값을 추가하거나 재정의하게 해 줘요.
per_replica: false: 단계가 어떤 replica가 시작되기 전에 서비스 전체에 대해 한 번 실행되는지 여부.

pre_start 단계는 서비스의 depends_on 조건이 충족된 후에만 실행되므로, 단계는 기본 서비스 명령이 하는 것처럼 그 의존성에 의존할 수 있어요. pre_start 컨테이너는 서비스와 같은 네트워크에 참여하므로 depends_on에 선언된 서비스에 도달할 수 있고, 서비스의 선언된 볼륨 마운트를 공유하므로 공유 볼륨에서 생성한 파일이 서비스에 보여요.

per_replica: false와 확장된(스케일된) 서비스에서는 replica 전체에 공유된 마운트(명명된 볼륨, 바인드 마운트)만 사용 가능해요. 인스턴스별 마운트(tmpfs, 익명 볼륨)는 단일 실행으로 처리할 수 없어요. 이는 오류가 아니에요. 단계는 인스턴스별 마운트에 접근하지 않고 실행돼요. per_replica: false 단계가 서비스와 공유해야 하는 데이터는 명명된 볼륨이나 바인드 마운트에 있어야 해요.

현재 정의에 대해 이미 성공한 pre_start 단계는 이후의 up에서나 서비스 컨테이너가 restart 정책 아래에서 재시작할 때 다시 실행되지 않아요. 단계는 정의가 변경되거나, 이전 실행이 성공하지 않았거나, 서비스가 재생성될 때 다시 실행돼요. 예를 들어 서비스 구성 변경이나 명시적 강제 재생성 후에요.

services:
  app:
    image: myapp:latest
    depends_on:
      db:
        condition: service_healthy
    pre_start:
      - command: ["./manage.py", "migrate"]
      - image: busybox
        command: sh -c 'chown -R 1000:1000 /data'
    volumes:
      - data:/data

  db:
    image: postgres:16

volumes:
  data:

`pre_stop`

pre_stop은 컨테이너가 중지되기 전에 실행할 수명 주기 훅의 시퀀스를 정의해요. 컨테이너가 스스로 중지하거나 갑자기 종료되면 이 훅은 실행되지 않아요.

구성은 post_start와 동등해요.

`privileged`

privileged는 서비스 컨테이너가 높은 권한으로 실행되도록 구성해요. 지원 여부와 실제 영향은 플랫폼별이에요.

`profiles`

profiles는 서비스가 활성화될 명명된 프로필 목록을 정의해요. 할당되지 않으면 서비스는 항상 시작되지만, 할당되면 프로필이 활성화될 때만 시작돼요.

존재한다면 profiles는 [a-zA-Z0-9][a-zA-Z0-9_.-]+의 정규식 형식을 따라요.

services:
  frontend:
    image: frontend
    profiles: ["frontend"]

  phpmyadmin:
    image: phpmyadmin
    depends_on:
      - db
    profiles:
      - debug

`provider`

provider는 Compose가 직접 관리하지 않는 서비스를 정의하는 데 사용할 수 있어요. Compose는 서비스 수명 주기를 전용 또는 타사 구성 요소에 위임해요.

  database:
    provider:
      type: awesomecloud
      options:
        type: mysql
        foo: bar
  app:
    image: myapp
    depends_on:
       - database

Compose가 애플리케이션을 실행할 때 awesomecloud 바이너리가 database 서비스 설정을 관리하는 데 사용돼요. 의존 서비스 app은 리소스에 접근할 수 있도록 서비스 이름이 접두사로 붙은 추가 환경 변수를 받아요.

예시로 awesomecloud 실행이 변수 URL과 API_KEY를 만들었다고 가정하면, app 서비스는 환경 변수 DATABASE_URL과 DATABASE_API_KEY로 실행돼요.

Compose가 애플리케이션을 중지하면 awesomecloud 바이너리가 database 서비스 분해(tear down)를 관리하는 데 사용돼요.

Compose가 서비스 수명 주기를 외부 바이너리에 위임하는 메커니즘은 Compose 확장성 문서에 설명돼 있어요.

provider 속성 사용에 대한 자세한 내용은 provider 서비스 사용하기를 참고하세요.

`type`

type 속성은 필수예요. Compose가 설정·분해 수명 주기 이벤트를 관리하는 데 사용하는 외부 구성 요소를 정의해요.

`options`

options는 선택한 provider에 특화되어 있으며 compose 스펙이 검증하지 않아요.

`pull_policy`

pull_policy는 Compose가 이미지 pull을 시작할 때 내리는 결정을 정의해요. 가능한 값은 다음과 같아요.

always: Compose가 항상 레지스트리에서 이미지를 pull.
never: Compose가 레지스트리에서 이미지를 pull하지 않고 플랫폼 캐시 이미지에 의존. 캐시된 이미지가 없으면 실패가 보고됨.
missing: 이미지가 플랫폼 캐시에 없을 때만 Compose가 이미지를 pull. Compose Build Specification도 사용하지 않는다면 이것이 기본 옵션이에요. if_not_present는 하위 호환을 위해 이 값의 별칭으로 간주돼요. missing pull 정책을 사용해도 latest 태그는 항상 pull돼요.
build: Compose가 이미지를 빌드. 이미 이미 존재하면 Compose가 이미지를 다시 빌드.
daily: 마지막 pull이 24시간 전에 이루어졌다면 Compose가 레지스트리에서 이미지 업데이트를 확인.
weekly: 마지막 pull이 7일 전에 이루어졌다면 Compose가 레지스트리에서 이미지 업데이트를 확인.
every_<duration>: 마지막 pull이 <duration> 이전에 이루어졌다면 Compose가 레지스트리에서 이미지 업데이트를 확인. 기간은 주(w), 일(d), 시(h), 분(m), 초(s) 또는 이들의 조합으로 표현할 수 있어요.

services:
  test:
    image: nginx
    pull_policy: every_12h

`read_only`

read_only는 서비스 컨테이너를 읽기 전용 파일시스템으로 생성하도록 구성해요.

`restart`

restart는 플랫폼이 컨테이너 종료 시 적용하는 정책을 정의해요.

no: 기본 재시작 정책. 어떤 상황에서도 컨테이너를 재시작하지 않음.
always: 컨테이너가 제거될 때까지 항상 재시작하는 정책.
on-failure[:max-retries]: 종료 코드가 오류를 나타내면 컨테이너를 재시작하는 정책. 선택적으로 Docker 데몬이 시도하는 재시작 횟수를 제한.
unless-stopped: 종료 코드와 관계없이 컨테이너를 재시작하지만 서비스가 중지되거나 제거되면 재시작을 멈추는 정책.

    restart: "no"
    restart: always
    restart: on-failure
    restart: on-failure:3
    restart: unless-stopped

재시작 정책에 대한 더 자세한 정보는 Docker run 참조 페이지의 Restart Policies (--restart) 섹션에서 찾을 수 있어요.

`runtime`

runtime은 서비스 컨테이너에 사용할 런타임을 지정해요.

예를 들어 runtime은 "runc" 같은 OCI Runtime Spec의 구현 이름일 수 있어요.

web:
  image: busybox:latest
  command: true
  runtime: runc

기본값은 runc예요. 다른 런타임을 사용하려면 대체 런타임을 참고하세요.

`scale`

scale은 이 서비스에 대해 배포할 기본 컨테이너 수를 지정해요. 둘 다 설정되면 scale은 Deploy Specification의 replicas 속성과 일치해야 해요.

`secrets`

secrets 속성은 secrets 최상위 요소가 정의한 민감 데이터에 대한 접근을 서비스 단위로 허용해요. 서비스는 여러 secrets에 접근이 허용될 수 있어요.

두 가지 다른 구문 변형이 지원돼요: 짧은 구문과 긴 구문. secrets의 긴·짧은 구문은 같은 Compose 파일에서 사용할 수 있어요.

Compose는 secret이 플랫폼에 존재하지 않거나 Compose 파일의 secrets 최상위 섹션에 정의되어 있지 않으면 오류를 보고해요.

최상위 secrets에 secret을 정의한다고 해서 서비스에 접근을 부여하는 것은 아니에요. 그런 부여는 서비스 스펙 안에서 secrets 서비스 요소로 명시해야 해요.

짧은 구문 (Short syntax)

짧은 구문 변형은 secret 이름만 지정해요. 이는 컨테이너에 secret 접근을 허용하고 컨테이너 안의 /run/secrets/<secret_name>에 읽기 전용으로 마운트해요. 소스 이름과 대상 마운트 지점 모두 secret 이름으로 설정돼요.

다음 예시는 짧은 구문으로 frontend 서비스에 server-certificate secret 접근을 허용해요. server-certificate의 값은 ./server.cert 파일의 내용으로 설정돼요.

services:
  frontend:
    image: example/webapp
    secrets:
      - server-certificate
secrets:
  server-certificate:
    file: ./server.cert

긴 구문 (Long syntax)

긴 구문은 서비스 컨테이너 안에서 secret이 어떻게 생성되는지 더 세밀하게 제어해요.

source: 플랫폼에 존재하는 secret의 이름.
target: 서비스 작업 컨테이너의 /run/secrets/에 마운트할 파일의 이름, 또는 다른 위치가 필요하면 파일의 절대 경로. 지정하지 않으면 source가 기본값.
uid, gid: 서비스 작업 컨테이너의 /run/secrets/ 안에서 파일을 소유하는 숫자 uid/gid.
mode: 서비스 작업 컨테이너의 /run/secrets/에 마운트할 파일의 권한, 8진수 표기. 기본값은 전 세계 읽기 권한(mode 0444). 쓰기 비트는 설정돼 있으면 무시해야 해요. 실행 비트는 설정될 수 있어요.

uid, gid, mode 속성 지원은 secret의 소스가 environment일 때만 Docker Compose에서 구현된다는 점에 유의하세요. 소스가 file이면 Compose는 내부적으로 uid 재매핑을 허용하지 않는 바인드 마운트를 사용하며, 이 속성들은 조용히 무시돼요.

다음 예시는 컨테이너 안의 my-token secret 파일 이름을 설정하고, mode를 0440(그룹 읽기)으로 설정하며 사용자와 그룹을 103으로 설정해요. my-token의 값은 MY_TOKEN 환경 변수에서 읽혀요.

services:
  frontend:
    image: example/webapp
    secrets:
      - source: my-token
        uid: "103"
        gid: "103"
        mode: 0o440
secrets:
  my-token:
    environment: "MY_TOKEN"

`security_opt`

security_opt는 각 컨테이너의 기본 라벨링 스킴을 재정의해요.

옵션은 option=value 또는 option:value 구문을 받아들여요. no-new-privileges 같은 불리언 옵션은 값을 완전히 생략할 수 있는데, 그 경우 옵션은 활성화된 것으로 처리돼요. 다음 구문은 모두 동등해요.

security_opt:
  - no-new-privileges
  - no-new-privileges=true
  - no-new-privileges:true

security_opt:
  - label=user:USER
  - label=role:ROLE

재정의할 수 있는 추가 기본 라벨링 스킴은 보안 구성을 참고하세요.

`shm_size`

shm_size는 서비스 컨테이너가 허용하는 공유 메모리(Linux의 /dev/shm 파티션) 크기를 구성해요. byte value(바이트 값)으로 지정돼요.

`stdin_open`

stdin_open은 서비스 컨테이너가 할당된 stdin으로 실행되도록 구성해요. 이는 -i 플래그로 컨테이너를 실행하는 것과 같아요. 자세한 내용은 stdin 열어 두기를 참고하세요.

지원되는 값은 true 또는 false예요.

`stop_grace_period`

stop_grace_period는 컨테이너가 SIGTERM(또는 stop_signal로 지정된 중지 시그널)을 처리하지 못할 때 Compose가 컨테이너를 중지하려 시도하기 전에 기다려야 하는 시간을 지정해요. duration(기간)으로 지정돼요.

    stop_grace_period: 1s
    stop_grace_period: 1m30s

SIGKILL을 보내기 전에 컨테이너가 종료될 기본값은 10초예요.

`stop_signal`

stop_signal은 Compose가 서비스 컨테이너를 중지하는 데 사용하는 시그널을 정의해요. 설정하지 않으면 컨테이너는 SIGTERM을 보내 Compose가 중지해요.

stop_signal: SIGUSR1

`storage_opt`

storage_opt는 서비스의 스토리지 드라이버 옵션을 정의해요.

storage_opt:
  size: '1G'

`sysctls`

sysctls는 컨테이너에 설정할 커널 파라미터를 정의해요. sysctls는 배열이나 맵을 사용할 수 있어요.

sysctls:
  net.core.somaxconn: 1024
  net.ipv4.tcp_syncookies: 0

sysctls:
  - net.core.somaxconn=1024
  - net.ipv4.tcp_syncookies=0

커널에서 네임스페이스화된 sysctls만 사용할 수 있어요. Docker는 호스트 시스템도 수정하는 컨테이너 안의 sysctls 변경을 지원하지 않아요. 지원되는 sysctls 개요는 런타임에 네임스페이스화된 커널 파라미터 (sysctls) 구성을 참고하세요.

`tmpfs`

tmpfs는 컨테이너 안에 임시 파일시스템을 마운트해요. 단일 값이거나 목록일 수 있어요.

tmpfs:
 - <path>
 - <path>:<options>

path: tmpfs가 마운트될 컨테이너 안의 경로.
options: tmpfs 마운트용 옵션의 쉼표로 구분된 목록.

사용 가능한 옵션:

mode: 파일시스템 권한을 설정.
uid: 마운트된 tmpfs를 소유하는 사용자 ID 설정.
gid: 마운트된 tmpfs를 소유하는 그룹 ID 설정.

services:
  app:
    tmpfs:
      - /data:mode=755,uid=1009,gid=1009
      - /run

`tty`

tty는 서비스 컨테이너를 TTY로 실행하도록 구성해요. 이는 -t 또는 --tty 플래그로 컨테이너를 실행하는 것과 같아요. 자세한 내용은 pseudo-TTY 할당을 참고하세요.

지원되는 값은 true 또는 false예요.

`ulimits`

ulimits는 컨테이너의 기본 ulimits를 재정의해요. 단일 제한의 정수나 soft/hard 제한의 매핑으로 지정돼요.

ulimits:
  nproc: 65535
  nofile:
    soft: 20000
    hard: 40000

`use_api_socket`

use_api_socket이 설정되면 컨테이너는 API 소켓을 통해 기본 컨테이너 엔진과 상호작용할 수 있어요. 자격 증명이 컨테이너 안에 마운트되므로 컨테이너는 컨테이너 엔진과 관련된 명령에 대한 순수 위임자로 작동해요. 일반적으로 컨테이너가 실행하는 명령은 레지스트리에 pull·push할 수 있어요.

`user`

user는 컨테이너 프로세스를 실행하는 데 사용되는 사용자를 재정의해요. 기본값은 이미지(Dockerfile USER 등)가 설정해요. 설정되지 않으면 root예요.

`userns_mode`

userns_mode는 서비스의 사용자 네임스페이스를 설정해요. 지원되는 값은 플랫폼별이며 플랫폼 구성에 따라 달라질 수 있어요.

userns_mode: "host"

`uts`

uts는 서비스 컨테이너에 설정된 UTS 네임스페이스 모드를 구성해요. 지정하지 않으면 지원되는 경우 UTS 네임스페이스를 할당하는 것은 런타임의 결정이에요. 사용 가능한 값은 다음과 같아요.

'host': 컨테이너가 호스트와 같은 UTS 네임스페이스를 사용하게 됨.

    uts: "host"

`volumes`

volumes 속성은 서비스 컨테이너가 접근할 수 있는 호스트 경로나 명명된 볼륨을 마운트해요. volumes로 여러 유형의 마운트를 정의할 수 있어요: volume, bind, tmpfs, npipe.

마운트가 호스트 경로이고 단일 서비스만 사용한다면 서비스 정의의 일부로 선언할 수 있어요. 여러 서비스에서 볼륨을 재사용하려면 명명된 볼륨을 volumes 최상위 요소에 선언해야 해요.

다음 예시는 명명된 볼륨(db-data)이 backend 서비스에 사용되고, 단일 서비스에 대해 바인드 마운트가 정의된 것을 보여 줘요.

services:
  backend:
    image: example/backend
    volumes:
      - type: volume
        source: db-data
        target: /data
        volume:
          nocopy: true
          subpath: sub
      - type: bind
        source: /var/run/postgres/postgres.sock
        target: /var/run/postgres/postgres.sock

volumes:
  db-data:

volumes 최상위 요소에 대한 자세한 내용은 볼륨(Volumes)을 참고하세요.

짧은 구문 (Short syntax)

짧은 구문은 볼륨 마운트(VOLUME:CONTAINER_PATH)나 접근 모드(VOLUME:CONTAINER_PATH:ACCESS_MODE)를 지정하는 콜론으로 구분된 값이 있는 단일 문자열을 사용해요.

VOLUME: 컨테이너를 호스팅하는 플랫폼의 호스트 경로(바인드 마운트) 또는 볼륨 이름일 수 있음.
CONTAINER_PATH: 볼륨이 마운트되는 컨테이너 안의 경로.
ACCESS_MODE: 쉼표로 구분된 , 옵션 목록:
- rw: 읽기·쓰기 접근. 지정하지 않으면 기본값.
- ro: 읽기 전용 접근.
- z: 바인드 마운트 호스트 내용이 여러 컨테이너 사이에 공유됨을 나타내는 SELinux 옵션.
- Z: 바인드 마운트 호스트 내용이 개인적이고 다른 컨테이너와 공유되지 않음을 나타내는 SELinux 옵션.

[!NOTE]

SELinux 재라벨링 바인드 마운트 옵션은 SELinux가 없는 플랫폼에서는 무시돼요.

[!NOTE] 상대 호스트 경로는 로컬 컨테이너 런타임에 배포하는 Compose만 지원해요. 상대 경로는 로컬 경우에만 적용되는 Compose 파일의 상위 디렉토리에서 해석되기 때문이에요. Compose가 비로컬 플랫폼에 배포하면 상대 호스트 경로를 사용하는 Compose 파일을 오류로 거부해요. 명명된 볼륨과의 모호함을 피하려면 상대 경로는 항상 .나 ..로 시작해야 해요.

[!NOTE]

바인드 마운트의 경우 짧은 구문은 호스트의 소스 경로에 디렉토리가 없으면 만든다. 이는 docker-compose 레거시와의 하위 호환을 위한 거예요. 긴 구문을 사용하고 create_host_path를 false로 설정하면 방지할 수 있어요.

긴 구문 (Long syntax)

긴 형식 구문은 짧은 형식으로 표현할 수 없는 추가 필드를 구성하게 해 줘요.

type: 마운트 유형. volume, bind, tmpfs, image, npipe 또는 cluster.
source: 마운트 소스. 바인드 마운트의 호스트 경로, 이미지 마운트의 Docker 이미지 참조, 또는 최상위 volumes 키에 정의된 볼륨 이름. tmpfs 마운트에는 적용되지 않음.
target: 볼륨이 마운트되는 컨테이너 안의 경로.
read_only: 볼륨을 읽기 전용으로 설정하는 플래그.
bind: 추가 바인드 옵션을 구성하는 데 사용:
- propagation: 바인드에 사용되는 전파 모드.
- create_host_path: 호스트의 소스 경로에 아무것도 없으면 디렉토리를 생성. 기본값 true.
- selinux: SELinux 재라벨링 옵션 z (공유) 또는 Z (개인).
volume: 추가 볼륨 옵션 구성:
- nocopy: 볼륨이 생성될 때 컨테이너에서 데이터 복사를 비활성화하는 플래그.
- subpath: 볼륨 루트 대신 마운트할 볼륨 안의 경로.
tmpfs: 추가 tmpfs 옵션 구성:
- size: tmpfs 마운트의 바이트 단위 크기 (숫자 또는 바이트 단위).
- mode: 8진수로 된 Unix 권한 비트로서의 tmpfs 마운트 파일 모드. Docker Compose 2.14.0 버전에서 도입.
image: 추가 이미지 옵션 구성:
- subpath: 이미지 루트 대신 마운트할 소스 이미지 안의 경로. Docker Compose 버전 2.35.0에서 사용 가능.
consistency: 마운트의 일관성 요구사항. 사용 가능한 값은 플랫폼별.

[!TIP]

큰 저장소나 모노레포를 다루거나, 코드베이스와 더 이상 규모가 맞지 않는 가상 파일 시스템을 사용하고 있나요? Compose는 이제 동기화된 파일 공유(Synchronized file shares)를 활용해 바인드 마운트용 파일 공유를 자동으로 생성해요. 유료 구독으로 Docker에 로그인하고 Docker Desktop 설정에서 실험적 기능에 접근(Access experimental features) 과 Compose로 동기화된 파일 공유 관리(Manage Synchronized file shares with Compose) 를 모두 활성화했는지 확인하세요.

`volumes_from`

volumes_from은 다른 서비스나 컨테이너의 모든 볼륨을 마운트해요. 선택적으로 읽기 전용 접근 ro 또는 읽기·쓰기 rw를 지정할 수 있어요. 접근 수준을 지정하지 않으면 읽기·쓰기 접근이 사용돼요.

Compose가 관리하지 않는 컨테이너에서 볼륨을 마운트하려면 container: 접두사를 사용할 수도 있어요.

volumes_from:
  - service_name
  - service_name:ro
  - container:container_name
  - container:container_name:rw

`working_dir`

working_dir는 이미지가 지정한 컨테이너의 작업 디렉토리를 재정의해요. 예: Dockerfile의 WORKDIR.

Docker Compose에서 서비스 정의하기