도커 첫걸음 5편 — Docker Compose로 팀과 협업하기: compose.yaml 하나로 온보딩을 한 줄로

들어가며 — docker run 세 번 대신 파일 하나

크게 보기

4편에서 만든 API 서버에 데이터베이스를 붙인다고 해 봅시다. 3편과 4편에서 배운 대로라면 이렇게 됩니다.

docker network create lab
docker run -d --name db --network lab -e POSTGRES_PASSWORD=secret -v pgdata:/var/lib/postgresql/data postgres:17
docker build -t hello-api:dev .
docker run -d --name api --network lab -p 8000:8000 -e DATABASE_URL=postgresql://postgres:secret@db:5432/postgres hello-api:dev

동작은 하지만, 이걸 팀원에게 "README 보고 순서대로 치세요"라고 할 수는 없습니다. 한 글자만 틀려도 안 되고, 서비스가 하나 늘 때마다 문서가 길어집니다. 1편에서 도커로 없애겠다던 바로 그 "README대로 했는데 안 돼요"가 돌아옵니다.

Docker Compose는 이 명령들을 compose.yaml이라는 파일 하나에 적어 두고, docker compose up 한 줄로 전부 띄우는 도구입니다. 파일은 저장소에 커밋되니 팀 전체가 같은 환경을 갖게 됩니다. 협업하는 도커의 완성형입니다.

1. 첫 compose.yaml — API + DB

4편의 hello-api 폴더에 compose.yaml을 만듭니다. 위의 긴 명령 네 줄이 이렇게 바뀝니다.

services:
  api:
    build: .
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: postgresql://postgres:${DB_PASSWORD}@db:5432/postgres
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:17
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 3s
      retries: 10

volumes:
  pgdata:

비밀번호는 파일에 직접 쓰지 않고 같은 폴더의 .env 파일에서 읽습니다. Compose는 .env를 자동으로 읽어 ${DB_PASSWORD} 자리에 넣습니다.

echo "DB_PASSWORD=secret" > .env

이제 띄웁니다.

docker compose up -d --build

이미지 빌드, 네트워크 생성, 볼륨 생성, DB 시작, DB가 준비될 때까지 대기, API 시작 — 네 줄이 하던 일을 한 줄이 순서대로 해냅니다.

2. 가장 중요한 개념 — 컨테이너끼리는 서비스 이름으로 부른다

위 DATABASE_URL을 다시 보세요. @localhost:5432가 아니라 @db:5432입니다. 초보자가 Compose에서 가장 많이 막히는 지점이 바로 여기입니다.

• 내 컴퓨터 → 컨테이너: localhost:내쪽포트 (ports로 뚫은 통로)
• 컨테이너 → 컨테이너: 서비스이름:컨테이너쪽포트 (Compose 네트워크 안의 이름)
• 컨테이너 안에서 localhost는 그 컨테이너 자신입니다. api 컨테이너 안에서 localhost:5432를 찾으면 api 컨테이너 안에는 DB가 없으니 Connection refused가 납니다.

그래서 db 서비스에는 ports:가 아예 없어도 api는 DB에 잘 접속합니다. ports는 내 컴퓨터에서 DB 도구로 들여다보고 싶을 때만 추가하면 됩니다.

3. 매일 쓰는 Compose 명령

docker compose 명령은 compose.yaml이 있는 폴더에서 실행합니다.

4. 개발 모드 — 코드를 고치면 바로 반영되게

4편에서는 코드를 고칠 때마다 다시 빌드했습니다. 개발 중에는 번거롭죠. 소스 폴더를 컨테이너에 연결(바인드 마운트)하고 서버를 자동 재시작 모드로 띄우면 재빌드가 필요 없습니다. 개발 전용 설정은 compose.override.yaml에 따로 적는 것이 관례입니다 — Compose는 이 파일이 있으면 compose.yaml 위에 자동으로 덧씌웁니다.

# compose.override.yaml — 로컬 개발 전용
services:
  api:
    volumes:
      - ./:/app
    command: ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

docker compose up -d로 다시 띄운 뒤 main.py의 메시지를 고치고 저장하면, 몇 초 안에 curl localhost:8000 결과가 바뀝니다. 2편에서 OrbStack의 장점으로 "파일 공유가 빠르다"를 꼽은 이유가 이 개발 방식 때문입니다.

5. 이미지 공유 — 레지스트리로 push, 동료는 pull

지금까지는 팀원 각자가 build: .로 이미지를 직접 빌드했습니다. 소스 코드가 있는 개발자에게는 이게 가장 간단합니다. 하지만 이런 경우에는 이미 만든 이미지를 공유하는 편이 낫습니다.

• 기획자·디자이너·QA처럼 코드를 빌드할 필요 없이 실행만 하면 되는 동료
• 빌드가 오래 걸리거나, 특정 도구(GPU 라이브러리 등)가 필요한 이미지
• 서버에 배포할 정확히 그 이미지를 모두가 테스트해야 할 때

크게 보기

레지스트리는 여러 곳이 있습니다.

GitHub을 쓰는 팀이라면 GHCR이 가장 자연스럽습니다. GitHub에서 Settings → Developer settings → Personal access tokens에서 write:packages 권한이 있는 토큰(classic)을 만든 뒤 로그인합니다.

echo "여기에_토큰" | docker login ghcr.io -u 내GitHub아이디 --password-stdin

이미지에 레지스트리 주소가 포함된 이름을 붙이고 올립니다. 이미지 이름은 소문자만 쓸 수 있습니다.

docker tag hello-api:0.2 ghcr.io/우리조직/hello-api:0.2
docker push ghcr.io/우리조직/hello-api:0.2

맥과 x86 서버를 모두 지원해야 하면 4편의 buildx 멀티 플랫폼 빌드로 --push합니다. 동료의 compose.yaml에서는 build: 대신 image:로 받아 씁니다.

services:
  api:
    image: ghcr.io/우리조직/hello-api:0.2

docker compose pull
docker compose up -d

6. 사람 대신 CI가 빌드하게 — GitHub Actions

손으로 빌드하고 push하면 누군가는 잊고, 누군가는 맥에서 arm64로만 올립니다(4편의 함정). 가장 좋은 방법은 main 브랜치에 코드가 합쳐질 때마다 CI가 자동으로 빌드해 올리는 것입니다. 저장소에 .github/workflows/docker.yml을 추가합니다.

name: docker

on:
  push:
    branches: [main]
    tags: ["v*"]

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v5

      - uses: docker/setup-qemu-action@v3
      - uses: docker/setup-buildx-action@v3

      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/${{ github.repository }}
          tags: |
            type=sha
            type=ref,event=branch
            type=semver,pattern={{version}}

      - uses: docker/build-push-action@v6
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

이 워크플로는 ① GitHub이 자동으로 주는 GITHUB_TOKEN으로 GHCR에 로그인하고(별도 토큰 불필요) ② amd64·arm64 두 아키텍처를 빌드해 ③ 커밋 해시(sha-3f9a2c1), 브랜치 이름(main), 버전 태그(v1.4.2를 push하면 1.4.2)를 붙여 올리고 ④ 빌드 캐시를 GitHub에 저장해 다음 빌드를 빠르게 합니다. 4편에서 배운 태그 습관과 멀티 플랫폼이 사람 손을 거치지 않고 지켜집니다.

7. 팀 규칙 — 저장소에 무엇을 커밋하나

도커 협업의 약속은 2편에서 말했듯 "같은 도구"가 아니라 "같은 파일"입니다. 저장소에 들어갈 것과 들어가면 안 될 것을 정해 둡니다.

.env.example은 이렇게 생겼습니다.

# 복사해서 .env로 만든 뒤 값을 채우세요: cp .env.example .env
DB_PASSWORD=change-me

그리고 팀 규칙 몇 가지를 README에 적어 둡니다.

8. 복사해서 쓰는 README 온보딩 절

이 시리즈의 목표였던 "신규 팀원이 한 줄로 시작"을 README로 옮기면 이렇습니다. 여러분의 프로젝트에 맞게 고쳐 쓰세요.

## 로컬 개발 환경

### 1. 준비물
- 도커 도구 하나 (맥: OrbStack 또는 Rancher Desktop / 윈도우: Rancher Desktop 또는 WSL2 + Docker Engine)
- 설치 확인: `docker compose version`

### 2. 실행
```bash
cp .env.example .env
docker compose up -d --build
```
- API: http://localhost:8000/docs

### 3. 자주 쓰는 명령
| 할 일 | 명령 |
|---|---|
| 로그 | `docker compose logs -f api` |
| DB 접속 | `docker compose exec db psql -U postgres` |
| 전부 내리기 | `docker compose down` |
| DB 초기화 | `docker compose down -v && docker compose up -d` |

9. 시리즈를 마치며 — 전체 지도

다섯 편을 한 장으로 접으면 이렇습니다.

도커를 어렵게 만드는 것은 명령어의 개수가 아니라 무엇이 어디에 있는지에 대한 그림입니다. 이미지는 틀, 컨테이너는 붕어빵, 볼륨은 냉장고, 레지스트리는 마트, compose.yaml은 팀의 약속. 이 그림만 있으면 처음 보는 옵션도 "아, 이건 내 쪽:컨테이너 쪽이구나" 하고 읽힙니다. 이제 팀 저장소에 compose.yaml 하나를 추가하는 것으로 시작해 보세요.

참고 자료

• Docker 문서, Docker Compose overview · Compose file reference
• Docker 문서, Control startup order (depends_on, healthcheck)
• Docker 문서, Merge Compose files (compose.override.yaml) · Compose Watch
• GitHub 문서, Working with the Container registry
• Docker 문서, GitHub Actions로 멀티 플랫폼 이미지 빌드
• 시리즈: 1편 · 2편 · 3편 · 4편