Docker 완전 정복 2025: 컨테이너 기초부터 멀티스테이지 빌드, Docker Compose, 프로덕션 배포까지

# cgroup으로 메모리를 256MB로 제한하는 예시
sudo cgcreate -g memory:mycontainer
echo 268435456 | sudo tee /sys/fs/cgroup/memory/mycontainer/memory.limit_in_bytes

┌─────────────────────────────────────────────────────────────┐
│                   컨테이너 아키텍처                           │
├──────────┬──────────┬──────────┬──────────┐                 │
│  App A   │  App B   │  App C   │  App D   │                 │
├──────────┼──────────┼──────────┼──────────┤                 │
│  Bins/   │  Bins/   │  Bins/   │  Bins/   │                 │
│  Libs    │  Libs    │  Libs    │  Libs    │                 │
├──────────┴──────────┴──────────┴──────────┤                 │
│           Container Runtime                │                 │
├────────────────────────────────────────────┤                 │
│              Host OS Kernel                │                 │
├────────────────────────────────────────────┤                 │
│              Infrastructure                │                 │
└────────────────────────────────────────────┘                 │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                      VM 아키텍처                             │
├──────────┬──────────┬──────────┬──────────┐                 │
│  App A   │  App B   │  App C   │  App D   │                 │
├──────────┼──────────┼──────────┼──────────┤                 │
│  Bins/   │  Bins/   │  Bins/   │  Bins/   │                 │
│  Libs    │  Libs    │  Libs    │  Libs    │                 │
├──────────┼──────────┼──────────┼──────────┤                 │
│ Guest OS │ Guest OS │ Guest OS │ Guest OS │                 │
├──────────┴──────────┴──────────┴──────────┤                 │
│              Hypervisor                    │                 │
├────────────────────────────────────────────┤                 │
│              Host OS                       │                 │
├────────────────────────────────────────────┤                 │
│              Infrastructure                │                 │
└────────────────────────────────────────────┘                 │
└─────────────────────────────────────────────────────────────┘

┌─────────────┐     REST API     ┌─────────────────────┐
│   Docker     │ ──────────────> │   Docker Daemon      │
│   CLI        │                 │   (dockerd)          │
│              │                 │                      │
│  docker run  │                 │  ┌─────────────────┐ │
│  docker build│                 │  │   containerd    │ │
│  docker pull │                 │  │                 │ │
└─────────────┘                 │  │  ┌───────────┐  │ │
                                │  │  │   runc    │  │ │
                                │  │  └───────────┘  │ │
                                │  └─────────────────┘ │
                                └─────────────────────┘

# 이미지 관리 명령어
docker images                    # 로컬 이미지 목록
docker pull nginx:1.25-alpine    # 이미지 다운로드
docker image inspect nginx       # 이미지 상세 정보
docker image prune               # 사용하지 않는 이미지 정리

# 컨테이너 실행 및 관리
docker run -d --name my-nginx -p 8080:80 nginx:1.25-alpine
docker ps                        # 실행 중인 컨테이너 목록
docker logs my-nginx             # 로그 확인
docker exec -it my-nginx /bin/sh # 컨테이너 내부 접속
docker stop my-nginx             # 정지
docker rm my-nginx               # 삭제

# 볼륨 생성 및 사용
docker volume create my-data
docker run -d -v my-data:/app/data my-app
docker run -d -v /host/path:/container/path my-app  # 바인드 마운트

# 네트워크 생성 및 관리
docker network create my-network
docker run -d --network my-network --name api my-api
docker run -d --network my-network --name db postgres
# api 컨테이너에서 db:5432로 접근 가능

# 베이스 이미지 선택
FROM node:20-alpine

# 메타데이터 추가
LABEL maintainer="dev@example.com"
LABEL version="1.0"

# 빌드 시 변수 (빌드 시에만 사용)
ARG NODE_ENV=production

# 환경 변수 (런타임에도 사용)
ENV NODE_ENV=$NODE_ENV
ENV PORT=3000

# 작업 디렉토리 설정
WORKDIR /app

# 파일 복사 (COPY 권장)
COPY package*.json ./

# 명령어 실행
RUN npm ci --only=production

# 소스 코드 복사
COPY . .

# 포트 문서화 (실제 포트 열지는 않음)
EXPOSE 3000

# 컨테이너 상태 체크
HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

# 실행할 사용자 변경 (보안)
USER node

# 컨테이너 시작 시 실행할 명령
ENTRYPOINT ["node"]
CMD ["server.js"]

# CMD만 사용 - docker run 시 완전 대체 가능
CMD ["python", "app.py"]
# docker run my-image python test.py  (CMD가 test.py로 대체됨)

# ENTRYPOINT만 사용 - 항상 실행됨
ENTRYPOINT ["python"]
# docker run my-image app.py  (python app.py로 실행)

# ENTRYPOINT + CMD 조합 (가장 유연)
ENTRYPOINT ["python"]
CMD ["app.py"]
# docker run my-image         -> python app.py
# docker run my-image test.py -> python test.py

# ARG: 빌드 시에만 존재 (런타임에는 없음)
ARG BUILD_VERSION=1.0
RUN echo "Building version: $BUILD_VERSION"

# ENV: 빌드 시 + 런타임 모두 존재
ENV APP_VERSION=1.0
# 컨테이너 실행 시에도 APP_VERSION 사용 가능

# 나쁜 예: 소스 변경 시 npm install 재실행
COPY . .
RUN npm install

# 좋은 예: package.json 변경 시에만 npm install 재실행
COPY package*.json ./
RUN npm ci
COPY . .

# 나쁜 예: 3개의 레이어 생성
RUN apt-get update
RUN apt-get install -y curl
RUN rm -rf /var/lib/apt/lists/*

# 좋은 예: 1개의 레이어 생성 + 캐시 정리
RUN apt-get update && \
    apt-get install -y --no-install-recommends curl && \
    rm -rf /var/lib/apt/lists/*

# .dockerignore
node_modules
.git
.env
*.md
Dockerfile
docker-compose*.yml
.github
coverage
dist

# Stage 1: 빌드 환경
FROM node:20 AS builder
WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

# Stage 2: 프로덕션 환경
FROM node:20-alpine AS production
WORKDIR /app

# 프로덕션 의존성만 설치
COPY package*.json ./
RUN npm ci --only=production && npm cache clean --force

# 빌드 결과물만 복사
COPY --from=builder /app/dist ./dist

# 보안: non-root 사용자
USER node

EXPOSE 3000
CMD ["node", "dist/server.js"]

# Stage 1: 빌드
FROM golang:1.22-alpine AS builder
WORKDIR /app

COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /app/server .

# Stage 2: 최소 이미지
FROM scratch
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=builder /app/server /server

EXPOSE 8080
ENTRYPOINT ["/server"]

# Stage 1: 빌드
FROM eclipse-temurin:21-jdk AS builder
WORKDIR /app

COPY gradlew build.gradle settings.gradle ./
COPY gradle ./gradle
RUN ./gradlew dependencies --no-daemon

COPY src ./src
RUN ./gradlew bootJar --no-daemon

# Stage 2: 런타임
FROM eclipse-temurin:21-jre-alpine
WORKDIR /app

COPY --from=builder /app/build/libs/*.jar app.jar

RUN addgroup -S spring && adduser -S spring -G spring
USER spring:spring

EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

# Stage 1: 의존성 빌드
FROM python:3.12-slim AS builder
WORKDIR /app

RUN pip install --no-cache-dir poetry
COPY pyproject.toml poetry.lock ./
RUN poetry export -f requirements.txt -o requirements.txt --without-hashes
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt

# Stage 2: 런타임
FROM python:3.12-slim
WORKDIR /app

COPY --from=builder /install /usr/local
COPY . .

RUN useradd --create-home appuser
USER appuser

EXPOSE 8000
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "app.main:app"]

# docker-compose.yml
version: '3.9'

services:
  api:
    build:
      context: ./api
      dockerfile: Dockerfile
    ports:
      - '3000:3000'
    environment:
      - NODE_ENV=production
      - DATABASE_URL=postgresql://postgres:secret@db:5432/myapp
      - REDIS_URL=redis://redis:6379
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    healthcheck:
      test: ['CMD', 'wget', '--spider', 'http://localhost:3000/health']
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    restart: unless-stopped
    networks:
      - app-network

  db:
    image: postgres:16-alpine
    volumes:
      - postgres-data:/var/lib/postgresql/data
      - ./init-scripts:/docker-entrypoint-initdb.d
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: secret
    ports:
      - '5432:5432'
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - app-network

  redis:
    image: redis:7-alpine
    command: redis-server --appendonly yes --maxmemory 256mb
    volumes:
      - redis-data:/data
    ports:
      - '6379:6379'
    networks:
      - app-network

  nginx:
    image: nginx:1.25-alpine
    ports:
      - '80:80'
      - '443:443'
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./nginx/ssl:/etc/nginx/ssl:ro
    depends_on:
      - api
    networks:
      - app-network

volumes:
  postgres-data:
    driver: local
  redis-data:
    driver: local

networks:
  app-network:
    driver: bridge

# .env 파일 사용
services:
  api:
    env_file:
      - .env
      - .env.production

# Docker Secrets (Swarm 모드)
services:
  api:
    secrets:
      - db_password
      - api_key

secrets:
  db_password:
    file: ./secrets/db_password.txt
  api_key:
    external: true

# 서비스 시작 (백그라운드)
docker compose up -d

# 서비스 로그 확인
docker compose logs -f api

# 서비스 스케일링
docker compose up -d --scale api=3

# 서비스 재빌드 + 재시작
docker compose up -d --build

# 서비스 중지 및 리소스 정리
docker compose down

# 볼륨까지 모두 삭제
docker compose down -v

# 특정 서비스만 재시작
docker compose restart api

# 실행 중인 서비스 상태 확인
docker compose ps

# docker-compose.yml (공통)
services:
  api:
    build: ./api

# docker-compose.override.yml (개발 환경 - 자동 로드)
services:
  api:
    volumes:
      - ./api:/app    # 핫 리로드용 마운트
    environment:
      - DEBUG=true
    command: npm run dev

# docker-compose.prod.yml (프로덕션)
services:
  api:
    environment:
      - NODE_ENV=production
    deploy:
      replicas: 3
      resources:
        limits:
          memory: 512M
          cpus: "0.5"

# 개발 환경 (자동으로 override 파일 로드)
docker compose up

# 프로덕션 환경
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

# 커스텀 네트워크 생성
docker network create my-app

# 같은 네트워크에서 컨테이너 실행
docker run -d --name api --network my-app my-api-image
docker run -d --name db --network my-app postgres

# api 컨테이너 내부에서 db 컨테이너에 접근
# 호스트명 "db"가 자동으로 해석됨
curl http://db:5432

# 특정 포트 매핑
docker run -p 8080:80 nginx

# 특정 인터페이스에만 바인딩
docker run -p 127.0.0.1:8080:80 nginx

# 랜덤 호스트 포트 할당
docker run -p 80 nginx

# 여러 포트 매핑
docker run -p 80:80 -p 443:443 nginx

# Docker Compose에서 자동 서비스 디스커버리
services:
  api-gateway:
    image: nginx
    depends_on:
      - user-service
      - order-service

  user-service:
    image: my-user-service
    # api-gateway에서 http://user-service:3000 으로 접근 가능

  order-service:
    image: my-order-service
    # api-gateway에서 http://order-service:3000 으로 접근 가능

# Node.js - 내장 node 사용자 활용
FROM node:20-alpine
WORKDIR /app
COPY --chown=node:node . .
RUN npm ci --only=production
USER node
CMD ["node", "server.js"]

# 커스텀 사용자 생성
FROM python:3.12-slim
RUN groupadd -r appgroup && useradd -r -g appgroup appuser
WORKDIR /app
COPY --chown=appuser:appgroup . .
USER appuser
CMD ["python", "app.py"]

docker run --read-only --tmpfs /tmp --tmpfs /var/run my-app

# Docker Compose에서
services:
  api:
    read_only: true
    tmpfs:
      - /tmp
      - /var/run

# Trivy로 취약점 스캔
trivy image my-app:latest

# 심각도 기준 필터링
trivy image --severity HIGH,CRITICAL my-app:latest

# Docker Scout (Docker Desktop 내장)
docker scout cves my-app:latest
docker scout recommendations my-app:latest

# Snyk
snyk container test my-app:latest

# 절대 하지 마세요
ENV API_KEY=sk-1234567890
COPY .env /app/.env

# 올바른 방법: 빌드 시 시크릿 마운트 (BuildKit)
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci

# 빌드 시 시크릿 전달
DOCKER_BUILDKIT=1 docker build --secret id=npmrc,src=.npmrc -t my-app .

# Rootless 모드로 Docker 설치
dockerd-rootless-setuptool.sh install

# 확인
docker info | grep -i rootless
# Security Options: rootless

# Docker Content Trust 활성화
export DOCKER_CONTENT_TRUST=1

# 서명된 이미지만 Pull 가능
docker pull my-registry/my-app:latest  # 서명 없으면 실패

# Cosign으로 이미지 서명 (Sigstore)
cosign sign my-registry/my-app:latest
cosign verify my-registry/my-app:latest

[보안 체크리스트]
- Non-root 사용자로 실행 (USER 지시어)
- 최소 베이스 이미지 사용 (Alpine, distroless, scratch)
- 이미지 취약점 정기 스캔 (Trivy, Snyk, Scout)
- Dockerfile에 시크릿/자격 증명 절대 포함 금지
- 읽기 전용 파일시스템 사용
- 네트워크 노출 최소화
- 리소스 제한 설정 (메모리, CPU)
- Docker Content Trust 활성화
- 정기적으로 베이스 이미지 업데이트
- 불필요한 패키지/도구 제거

# .github/workflows/docker-build.yml
name: Docker Build and Push

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: my-org/my-app

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to Container Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: my-username
          password: my-token

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/my-org/my-app
          tags: |
            type=ref,event=branch
            type=sha,prefix=
            type=semver,pattern=v{{version}}

      - name: Build and Push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: steps.meta.outputs.tags
          labels: steps.meta.outputs.labels
          cache-from: type=gha
          cache-to: type=gha,mode=max
          platforms: linux/amd64,linux/arm64

# Buildx 빌더 생성
docker buildx create --name multiarch --use

# 멀티 플랫폼 빌드 및 푸시
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --tag my-registry/my-app:latest \
  --push .

# GitHub Actions Cache
- name: Build with cache
  uses: docker/build-push-action@v5
  with:
    cache-from: type=gha
    cache-to: type=gha,mode=max

# Registry 기반 캐시
- name: Build with registry cache
  uses: docker/build-push-action@v5
  with:
    cache-from: type=registry,ref=ghcr.io/my-org/my-app:buildcache
    cache-to: type=registry,ref=ghcr.io/my-org/my-app:buildcache,mode=max

# 컨테이너 로그 드라이버 설정
docker run -d \
  --log-driver=json-file \
  --log-opt max-size=10m \
  --log-opt max-file=3 \
  my-app

# syslog 드라이버
docker run -d \
  --log-driver=syslog \
  --log-opt syslog-address=tcp://logserver:514 \
  my-app

# Docker Compose에서 로깅 설정
services:
  api:
    logging:
      driver: json-file
      options:
        max-size: '10m'
        max-file: '3'

# docker-compose.monitoring.yml
services:
  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    ports:
      - '9090:9090'

  cadvisor:
    image: gcr.io/cadvisor/cadvisor:latest
    volumes:
      - /:/rootfs:ro
      - /var/run:/var/run:ro
      - /sys:/sys:ro
      - /var/lib/docker/:/var/lib/docker:ro
    ports:
      - '8080:8080'

  grafana:
    image: grafana/grafana:latest
    volumes:
      - grafana-data:/var/lib/grafana
    ports:
      - '3000:3000'
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin

volumes:
  grafana-data:

# 메모리 제한: 512MB (초과 시 OOM Kill)
docker run -m 512m my-app

# CPU 제한: 1.5 코어
docker run --cpus="1.5" my-app

# 조합
docker run -m 512m --cpus="1.5" --memory-swap=1g my-app

# Docker Compose에서
services:
  api:
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '1.5'
        reservations:
          memory: 256M
          cpus: '0.5'

// Node.js 예시
process.on('SIGTERM', async () => {
  console.log('SIGTERM received. Graceful shutdown...')

  // 새 요청 거부
  server.close(async () => {
    // DB 연결 종료
    await db.close()
    // Redis 연결 종료
    await redis.quit()

    console.log('All connections closed. Exiting.')
    process.exit(0)
  })

  // 30초 후 강제 종료
  setTimeout(() => {
    console.error('Forced shutdown after timeout')
    process.exit(1)
  }, 30000)
})

# Dockerfile에서 올바른 ENTRYPOINT 형식
# exec 형식 사용 (SIGTERM이 직접 앱에 전달됨)
ENTRYPOINT ["node", "server.js"]

# shell 형식은 사용 금지 (SIGTERM이 sh에만 전달됨)
# ENTRYPOINT node server.js  # 이렇게 하지 마세요

# Dockerfile에서 헬스체크
HEALTHCHECK --interval=30s --timeout=3s --start-period=30s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1

# Docker Compose에서 헬스체크
services:
  api:
    healthcheck:
      test: ['CMD', 'curl', '-f', 'http://localhost:3000/health']
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

  db:
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 10s
      timeout: 5s
      retries: 5

# Docker와 거의 동일한 CLI
podman run -d -p 8080:80 nginx
podman ps
podman images

# Docker와의 호환성을 위한 별칭
alias docker=podman

# ctr - containerd 네이티브 CLI (저수준)
ctr images pull docker.io/library/nginx:latest
ctr run docker.io/library/nginx:latest my-nginx

# Docker와 동일한 UX
nerdctl run -d -p 8080:80 nginx
nerdctl compose up -d
nerdctl build -t my-app .

# 추가 기능: 이미지 암호화
nerdctl image encrypt --recipient jwe:public-key.pem my-app encrypted-app

# NVIDIA Container Toolkit 설치
distribution=ubuntu22.04
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | \
  sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

# 패키지 설치
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

# Docker 런타임 설정
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

# 모든 GPU 사용
docker run --gpus all nvidia/cuda:12.3-base nvidia-smi

# 특정 GPU만 사용
docker run --gpus '"device=0,1"' my-ml-app

# Docker Compose에서

services:
  ml-training:
    image: my-ml-app
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 2
              capabilities: [gpu]

# PyTorch 모델 서빙 Dockerfile
FROM pytorch/pytorch:2.2.0-cuda12.1-cudnn8-runtime

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY model/ ./model/
COPY serve.py .

EXPOSE 8000

HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD curl -f http://localhost:8000/health || exit 1

CMD ["python", "serve.py"]

# TensorFlow Serving
services:
  tf-serving:
    image: tensorflow/serving:latest-gpu
    ports:
      - '8501:8501'
    volumes:
      - ./models:/models
    environment:
      - MODEL_NAME=my_model
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

  triton-server:
    image: nvcr.io/nvidia/tritonserver:24.01-py3
    ports:
      - '8000:8000'
      - '8001:8001'
      - '8002:8002'
    volumes:
      - ./model-repository:/models
    command: tritonserver --model-repository=/models
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]