Module 2

왜 Docker가 필요한가?

Docker 핵심 개념

VM vs Container

Docker 실행 흐름

1. Dockerfile 작성     (설계도 작성)
         ↓
2. docker build        (이미지 생성)
         ↓
3. docker run          (컨테이너 실행)
         ↓
4. 컨테이너 안에서 앱 동작
         ↓
5. docker stop         (컨테이너 정지)
          

Docker Hub & 이미지 가져오기

# Docker Hub에서 공식 Python 이미지 가져오기
docker pull python:3.10-slim

# 가져온 이미지 확인
docker images

# 출력 예시:
# REPOSITORY   TAG          IMAGE ID       SIZE
# python       3.10-slim    a2c7e8f3d4b1   150MB
          

첫 컨테이너 실행하기

# 1. Hello World 컨테이너
docker run hello-world

# 2. Python 컨테이너에서 명령 실행
docker run python:3.10-slim python --version
# 출력: Python 3.10.x

# 3. 컨테이너 안에 들어가보기 (인터랙티브 모드)
docker run -it python:3.10-slim bash

# 컨테이너 내부에서:
python -c "print('Hello from Docker!')"
pip list
exit
          

기초 명령어 정리

컨테이너 생명주기

# 1. 백그라운드로 Nginx 컨테이너 실행
docker run -d --name my-nginx -p 8080:80 nginx

# 2. 실행 중인 컨테이너 확인
docker ps
# CONTAINER ID   IMAGE   ...   PORTS                  NAMES
# a1b2c3d4e5f6   nginx   ...   0.0.0.0:8080->80/tcp   my-nginx

# 3. 컨테이너 로그 확인
docker logs my-nginx

# 4. 컨테이너 정지
docker stop my-nginx

# 5. 컨테이너 삭제
docker rm my-nginx
          

실습: Docker 기초 명령어

requirements.txt 왜 중요한가?

fastapi
uvicorn
scikit-learn
pandas
joblib
              

fastapi==0.115.0
uvicorn==0.30.0
scikit-learn==1.5.1
pandas==2.2.2
joblib==1.4.2
numpy==1.26.4
              

requirements.txt 만들기

# 방법 1: 현재 환경의 모든 패키지 (비추천 — 불필요한 것까지 포함)
pip freeze > requirements.txt   # conda 환경 활성화 상태에서 실행

# 방법 2: 필요한 것만 직접 작성 (추천)
# requirements.txt 파일을 직접 편집

# 방법 3: 현재 설치된 버전 확인 후 직접 작성
pip show fastapi     # 버전 확인
pip show uvicorn
pip show scikit-learn
          

서비스 A: requirements.txt

# service-a-loan/requirements.txt

# 웹 프레임워크
fastapi==0.115.0
uvicorn==0.30.0

# ML 라이브러리
scikit-learn==1.5.1
pandas==2.2.2
joblib==1.4.2
numpy==1.26.4

# 유틸리티
pydantic==2.9.0
          

Dockerfile이란?

• Docker 이미지를 만들기 위한 설계도 (텍스트 파일)
• 각 줄이 하나의 레이어(Layer)를 생성
• 위에서 아래로 순차 실행
• 파일명은 정확히 Dockerfile (확장자 없음)

Dockerfile 주요 명령어

서비스 A: Dockerfile 작성

# service-a-loan/Dockerfile

# 1. 베이스 이미지: Python 3.10 경량 버전
FROM python:3.10-slim

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

# 3. 의존성 파일 먼저 복사 (캐시 최적화)
COPY requirements.txt .

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

# 5. 소스 코드 복사
COPY . .

# 6. 포트 문서화
EXPOSE 8000

# 7. 서버 실행 명령
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
          

왜 requirements.txt를 먼저 복사하나?

COPY . .
RUN pip install -r requirements.txt
              

COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
              

CMD vs ENTRYPOINT

CMD ["uvicorn", "app.main:app",
     "--host", "0.0.0.0",
     "--port", "8000"]
              

ENTRYPOINT ["uvicorn"]
CMD ["app.main:app",
     "--host", "0.0.0.0"]
              

베이스 이미지 선택 가이드

실습: Dockerfile 작성해보기

docker build: 이미지 만들기

# service-a-loan 디렉토리에서 실행
cd service-a-loan

# 이미지 빌드 (-t: 태그 지정, .: 현재 디렉토리)
docker build -t loan-api:v1 .

# 빌드 과정 출력 예시:
# [1/5] FROM python:3.10-slim
# [2/5] WORKDIR /app
# [3/5] COPY requirements.txt .
# [4/5] RUN pip install --no-cache-dir -r requirements.txt
# [5/5] COPY . .
# => exporting to image
# => naming to docker.io/library/loan-api:v1

# 빌드된 이미지 확인
docker images
          

docker run: 컨테이너 실행

# 기본 실행
docker run loan-api:v1

# 포트 매핑과 함께 실행
docker run -p 8000:8000 loan-api:v1

# 백그라운드 실행 + 이름 지정
docker run -d --name loan-service -p 8000:8000 loan-api:v1

# 실행 확인
docker ps
          

포트 매핑 이해하기

API 호출 테스트

# 1. 컨테이너 실행 (백그라운드)
docker run -d --name loan-service -p 8000:8000 loan-api:v1

# 2. 헬스체크
curl http://localhost:8000/health
# {"status": "healthy", "model_loaded": true}

# 3. 예측 요청
curl -X POST http://localhost:8000/predict \
  -H "Content-Type: application/json" \
  -d '{
    "annual_income": 5000,
    "employment_years": 3,
    "loan_amount": 2000,
    "debt_ratio": 35.5,
    "credit_grade": 2,
    "has_mortgage": 1,
    "num_credit_lines": 4
  }'

# 4. Swagger UI 확인
# 브라우저에서 http://localhost:8000/docs 접속
          

컨테이너 로그 & 디버깅

# 로그 확인
docker logs loan-service

# 실시간 로그 (tail -f 처럼)
docker logs -f loan-service

# 실행 중인 컨테이너에 접속
docker exec -it loan-service bash

# 컨테이너 안에서 확인
ls -la
cat requirements.txt
python -c "import sklearn; print(sklearn.__version__)"
exit

# 컨테이너 정지 & 삭제
docker stop loan-service
docker rm loan-service
          

.dockerignore 파일

# service-a-loan/.dockerignore

# 가상환경 (절대 이미지에 넣지 않기!)
venv/
.venv/
__pycache__/

# Git
.git/
.gitignore

# IDE
.vscode/
.idea/

# 데이터 (학습 데이터는 이미지에 불필요할 수 있음)
data/

# 테스트
tests/

# Docker 관련
Dockerfile
docker-compose.yml
.dockerignore

# 기타
*.pyc
*.pyo
.env
          

.dockerignore 왜 필요한가?

빌드 → 실행 전체 흐름

# 전체 흐름 한눈에

# 1. 이미지 빌드
docker build -t loan-api:v1 .

# 2. 이미지 크기 확인
docker images loan-api
# REPOSITORY   TAG   IMAGE ID       SIZE
# loan-api     v1    abc123def456   350MB

# 3. 컨테이너 실행
docker run -d --name loan-service -p 8000:8000 loan-api:v1

# 4. 동작 확인
curl http://localhost:8000/health

# 5. 정리
docker stop loan-service && docker rm loan-service
          

실습: 서비스 A Docker 실행

자주 쓰는 docker run 옵션

서비스 B Docker화 목표

서비스 B: requirements.txt

# service-b-review/requirements.txt

# 웹 프레임워크
fastapi==0.115.0
uvicorn==0.30.0

# Gemini API
google-genai>=1.0.0

# 유틸리티
pydantic==2.9.0
          

서비스 B: Dockerfile 작성

# service-b-review/Dockerfile

# 베이스 이미지
FROM python:3.10-slim

# 작업 디렉토리
WORKDIR /app

# 의존성 설치 (캐시 최적화)
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 소스 코드 복사
COPY . .

# 포트 문서화
EXPOSE 8000

# 서버 실행
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
          

환경변수로 API 키 주입 (-e 옵션)

# 방법 1: -e 옵션으로 직접 전달
docker run -d --name review-service \
  -p 8001:8000 \
  -e GEMINI_API_KEY="your-api-key-here" \
  review-api:v1

# 방법 2: --env-file로 파일에서 읽기 (추천)
# .env 파일 내용:
# GEMINI_API_KEY=your-api-key-here

docker run -d --name review-service \
  -p 8001:8000 \
  --env-file .env \
  review-api:v1

# 환경변수 확인
docker exec review-service env | grep GEMINI
          

환경변수 관리 패턴

# Dockerfile에 API 키 하드코딩
ENV GEMINI_API_KEY=sk-abc123

# 코드에 직접 작성
api_key = "sk-abc123"
              

# 코드에서 환경변수 읽기
import os
api_key = os.environ.get(
    "GEMINI_API_KEY"
)
if not api_key:
    raise ValueError(
        "GEMINI_API_KEY 필요"
    )
              

서비스 B 빌드 & 실행

# 1. 빌드
cd service-b-review
docker build -t review-api:v1 .

# 2. 실행 (API 키 주입)
docker run -d --name review-service \
  -p 8001:8000 \
  -e GEMINI_API_KEY="your-api-key-here" \
  review-api:v1

# 3. 헬스체크
curl http://localhost:8001/health

# 4. 리뷰 분석 테스트
curl -X POST http://localhost:8001/analyze \
  -H "Content-Type: application/json" \
  -d '{"review_text": "배송이 정말 빨라서 좋았습니다!"}'

# 5. Swagger UI 확인
# http://localhost:8001/docs
          

두 서비스 동시 실행

# 서비스 A: 포트 8000
docker run -d --name loan-service \
  -p 8000:8000 \
  loan-api:v1

# 서비스 B: 포트 8001
docker run -d --name review-service \
  -p 8001:8000 \
  -e GEMINI_API_KEY="your-key" \
  review-api:v1

# 두 서비스 모두 확인
docker ps
# CONTAINER ID  IMAGE          PORTS                   NAMES
# abc123...     loan-api:v1    0.0.0.0:8000->8000/tcp  loan-service
# def456...     review-api:v1  0.0.0.0:8001->8000/tcp  review-service

# 각각 테스트
curl http://localhost:8000/health   # 서비스 A
curl http://localhost:8001/health   # 서비스 B
          

자율실습 과제

체크리스트

트러블슈팅이 중요한 이유

• 포트 관련 오류 — 연결 거부, 포트 충돌
• 모듈 import 오류 — ModuleNotFoundError
• 의존성 오류 — 패키지 버전 충돌, 빌드 실패
• 파일 경로 오류 — FileNotFoundError

오류 1: 포트 연결 거부

# 상황: 컨테이너는 실행되었는데 접속이 안 됨
$ curl http://localhost:8000/health
curl: (7) Failed to connect to localhost port 8000: Connection refused
          

오류 1: 해결 과정 시연

# 1. 포트 매핑 확인
docker ps
# PORTS 열이 비어있으면 -p 옵션이 누락된 것

# 2. uvicorn 바인딩 주소 확인
docker logs loan-service
# INFO: Uvicorn running on http://127.0.0.1:8000
#                          ↑ 이게 문제! 0.0.0.0이어야 함

# 3. Dockerfile CMD 수정
# CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
#                                  ↑ 반드시 0.0.0.0

# 4. 다시 빌드 & 실행
docker stop loan-service && docker rm loan-service
docker build -t loan-api:v1 .
docker run -d --name loan-service -p 8000:8000 loan-api:v1
          

오류 2: 포트 충돌

# 상황: 이미 사용 중인 포트에 다시 바인딩하려 할 때
$ docker run -d -p 8000:8000 --name loan-2 loan-api:v1
Error: Bind for 0.0.0.0:8000 failed: port is already allocated
          

# 해결 1: 다른 포트 사용
docker run -d -p 8080:8000 --name loan-2 loan-api:v1

# 해결 2: 기존 컨테이너 정지 후 실행
docker stop loan-service && docker rm loan-service
docker run -d -p 8000:8000 --name loan-service loan-api:v1

# 해결 3: 어떤 프로세스가 포트를 쓰고 있는지 확인
# Linux/Mac
lsof -i :8000
# Windows
netstat -ano | findstr :8000
          

오류 3: ModuleNotFoundError

# 상황: 컨테이너 실행 시 바로 종료됨
$ docker logs loan-service
Traceback (most recent call last):
  File "/app/app/main.py", line 3, in <module>
    from app.model import LoanModel
  File "/app/app/model.py", line 1, in <module>
    import joblib
ModuleNotFoundError: No module named 'joblib'
          

# 1. requirements.txt에 joblib 추가
echo "joblib==1.4.2" >> requirements.txt

# 2. 다시 빌드 & 실행
docker build -t loan-api:v1 .
docker run -d --name loan-service -p 8000:8000 loan-api:v1
          

오류 4: FileNotFoundError (모델 파일)

# 상황: 모델 로딩 실패
$ docker logs loan-service
모델 파일 없음: models/loan_model.pkl

# 또는
FileNotFoundError: [Errno 2] No such file or directory: 'models/loan_model.pkl'
          

# 컨테이너 내부 확인
docker exec -it loan-service bash
ls -la models/
# 파일이 없거나 디렉토리 자체가 없음
              

오류 5: 환경변수 누락 (서비스 B)

# 상황: 서비스 B 실행 시 에러
$ docker logs review-service
ValueError: GEMINI_API_KEY 환경변수를 설정하세요

# 원인: -e 옵션으로 API 키를 전달하지 않음
          

# 해결: 환경변수 전달
docker stop review-service && docker rm review-service

# 방법 1: -e 옵션
docker run -d --name review-service \
  -p 8001:8000 \
  -e GEMINI_API_KEY="your-actual-key" \
  review-api:v1

# 방법 2: .env 파일
docker run -d --name review-service \
  -p 8001:8000 \
  --env-file .env \
  review-api:v1
          

오류 6: 의존성 빌드 실패

# 상황: docker build 중 pip install 실패
Step 4/7 : RUN pip install --no-cache-dir -r requirements.txt
ERROR: Could not find a version that satisfies the requirement
  scikit-learn==999.0.0

# 또는 C 라이브러리 빌드 에러
error: command 'gcc' failed: No such file or directory
          

# 1. 존재하는 버전으로 수정
# pip install scikit-learn== 로 가용 버전 확인

# 2. C 빌드 도구 필요 시 (slim 이미지에서)
FROM python:3.10-slim
RUN apt-get update && apt-get install -y \
    gcc \
    python3-dev \
    && rm -rf /var/lib/apt/lists/*
          

디버깅 필수 명령어 모음

트러블슈팅 실습: 문제 시나리오

시나리오 해답

트러블슈팅 체크리스트

1. docker ps -a → 컨테이너가 실행 중인가? 종료되었나?
2. docker logs [이름] → 에러 메시지가 있나?
3. docker exec -it [이름] bash → 내부 파일/환경 확인
4. 포트 매핑(-p) 확인 → PORTS 열에 표시되는가?
5. 환경변수(-e) 확인 → docker exec [이름] env
6. .dockerignore 확인 → 필요한 파일이 제외되지 않았나?
7. requirements.txt 확인 → 빠진 패키지가 없나?

Module 2 정리

• Docker = 앱 + 환경을 하나의 패키지로 묶는 기술
• 이미지 = 설계도 (읽기 전용), 컨테이너 = 실행 인스턴스
• Dockerfile로 이미지를 정의: FROM, WORKDIR, COPY, RUN, CMD
• requirements.txt는 반드시 버전 고정
• 레이어 캐시: 의존성 파일을 먼저, 소스 코드를 나중에 복사
• 환경변수로 민감 정보 관리 (-e, --env-file)
• .dockerignore로 불필요한 파일 제외