Source: Dev.to

제로부터 몇 분 안에 컨테이너화 — “내 컴퓨터에서는 동작해”는 이제 그만

아마 한 번쯤 들어보셨을 겁니다: “내 컴퓨터에서는 동작해.” Docker는 이 말을 사라지게 만들기 위해 존재합니다.
Docker는 애플리케이션과 그 모든 의존성(런타임, 라이브러리, 설정 파일 등)을 컨테이너라는 하나의 이식 가능한 단위에 묶어줍니다. 그 컨테이너는 노트북, 팀원의 Windows PC, CI 서버, 혹은 클라우드 VM 어디서든 동일하게 실행됩니다.

시작하기 전에 기억해 두면 좋은 개념

• Image → 설계도(객체지향에서 클래스와 같은 개념)
• Container → 이미지의 실행 인스턴스(객체와 같은 개념)
• Dockerfile → 이미지를 만들기 위한 레시피
• Docker Compose → 여러 컨테이너를 함께 오케스트레이션하는 도구

필수 사전 조건

• Docker Desktop 설치(Compose 포함)
• 기본 터미널 사용법 익숙함
• 컨테이너화할 프로젝트(예시로 Node.js, Python, 그리고 일반적인 접근법을 사용할 예정)

설치 확인

docker --version
# Docker version 26.x.x

docker compose version
# Docker Compose version v2.x.x

Dockerfile이란?

Dockerfile은 Docker가 위에서 아래로 읽어 이미지를 빌드하는 플레인 텍스트 파일입니다.

# 1. Base image — what you're building ON TOP OF
FROM node:20-alpine

# 2. Set the working directory inside the container
WORKDIR /app

# 3. Copy dependency files first (for layer caching)
COPY package*.json ./

# 4. Install dependencies
RUN npm install

# 5. Copy the rest of your source code
COPY . .

# 6. Expose the port your app listens on
EXPOSE 3000

# 7. The command to run when the container starts
CMD ["node", "server.js"]

팁: Dockerfile을 변경 빈도가 낮은 순으로 작성하세요. Docker는 각 레이어를 캐시하므로, 의존성 설치와 같은 안정적인 레이어는 변경되지 않을 때 재실행되지 않습니다.

예시 프로젝트 구조

my-app/
├── src/
│   └── index.js
├── package.json
├── package-lock.json
└── Dockerfile

FROM node:20-alpine

WORKDIR /app

# 캐시 효율을 위해 lockfile과 package.json을 먼저 복사
COPY package*.json ./
RUN npm ci --only=production

COPY src/ ./src/

EXPOSE 3000
CMD ["node", "src/index.js"]

# 이미지 빌드 및 태그 지정
docker build -t my-node-app .

# 호스트 포트 8080을 컨테이너 포트 3000에 매핑하여 실행
docker run -p 8080:3000 my-node-app

http://localhost:8080 에 접속하면 Docker 안에서 실행 중인 앱을 확인할 수 있습니다.

Python 예시

FROM python:3.12-slim

WORKDIR /app

# 의존성 설치
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000
CMD ["python", "-m", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

주의: --host 0.0.0.0 옵션은 기본적으로 많은 개발 서버가 127.0.0.1(컨테이너 내부)만 바인딩하기 때문에, 외부 연결을 허용하려면 반드시 0.0.0.0으로 바인딩해야 합니다.

Docker Compose로 다중 서비스 구성하기

실제 프로젝트는 보통 하나의 서비스만 있지 않습니다. 데이터베이스, 캐시, 백그라운드 워커 등이 필요하죠. Docker Compose를 사용하면 이 모든 서비스를 하나의 파일에 정의하고 동시에 실행할 수 있습니다.

# docker-compose.yml
services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgres://user:password@db:5432/mydb
      - REDIS_URL=redis://cache:6379
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started
    volumes:
      - .:/app              # 코드 변경 시 자동 리로드를 위해 마운트
      - /app/node_modules   # 호스트의 node_modules가 덮어쓰는 것을 방지

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
      POSTGRES_DB: mydb
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d mydb"]
      interval: 5s
      timeout: 5s
      retries: 5

  cache:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  postgres_data:

# 백그라운드에서 모든 서비스 시작
docker compose up -d

# 앱 로그 실시간 보기
docker compose logs -f app

# 전체 서비스 중지
docker compose down

# 볼륨까지 삭제 (데이터베이스 초기화)
docker compose down -v

비밀 정보는 절대 하드코딩하지 않기

.env 파일을 활용해 환경 변수를 관리합니다.

# .env  (git에 커밋되지 않도록 .gitignore에 추가!)
POSTGRES_PASSWORD=supersecret
API_KEY=abc123

Docker Compose는 같은 디렉터리의 .env 파일을 자동으로 읽어들입니다.

services:
  app:
    environment:
      - API_KEY=${API_KEY}
  db:
    environment:
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}

프로덕션 환경에서는 Docker Secrets, Vault, AWS Secrets Manager 등 전용 비밀 관리 솔루션을 사용하는 것이 좋습니다.

환경별 Compose 파일 분리

프로젝트 디렉터리 구조 예시:

my-app/
├── docker-compose.yml          # 기본 설정
├── docker-compose.dev.yml     # 개발용 오버라이드(핫 리로드, 디버그 포트)
└── docker-compose.prod.yml    # 프로덕션용 오버라이드(레플리카, 로깅)

개발용 오버라이드 (docker-compose.dev.yml)

services:
  app:
    volumes:
      - .:/app
    command: npm run dev
    environment:
      - NODE_ENV=development