Skip to content

DOCKER_GUIDE.md

Latest commit

 

History

History
535 lines (387 loc) · 10.2 KB

DOCKER_GUIDE.md

File metadata and controls

535 lines (387 loc) · 10.2 KB

🐳 Docker 사용 가이드

FastAPI + Streamlit 프로젝트를 Docker로 실행하는 상세 가이드입니다.

📋 목차

  1. 사전 준비
  2. 빠른 시작
  3. Docker Compose 명령어
  4. Makefile 사용
  5. 개발 모드 vs 프로덕션 모드
  6. 네트워크 구성
  7. 트러블슈팅

사전 준비

Docker 설치

설치 확인

docker --version
docker-compose --version

빠른 시작

1. 프로젝트 실행

# 이미지 빌드 및 컨테이너 시작
docker-compose up --build

# 백그라운드 실행
docker-compose up -d

2. 접속

3. 종료

# 컨테이너 중지
docker-compose down

# 컨테이너 중지 및 볼륨 삭제
docker-compose down -v

Docker Compose 명령어

기본 명령어

# 컨테이너 시작 (포그라운드)
docker-compose up

# 컨테이너 시작 (백그라운드)
docker-compose up -d

# 이미지 재빌드 후 시작
docker-compose up --build

# 컨테이너 중지
docker-compose down

# 컨테이너 중지 + 볼륨 삭제
docker-compose down -v

# 컨테이너 재시작
docker-compose restart

개별 서비스 제어

# 백엔드만 시작
docker-compose up backend

# 프론트엔드만 시작
docker-compose up frontend

# 백엔드만 재시작
docker-compose restart backend

# 프론트엔드만 재시작
docker-compose restart frontend

# 백엔드만 중지
docker-compose stop backend

로그 확인

# 모든 서비스 로그 (실시간)
docker-compose logs -f

# 백엔드 로그만
docker-compose logs -f backend

# 프론트엔드 로그만
docker-compose logs -f frontend

# 최근 100줄만 보기
docker-compose logs --tail=100 backend

상태 확인

# 실행 중인 컨테이너 확인
docker-compose ps

# 상세 정보 확인
docker-compose ps -a

# 리소스 사용량 확인
docker stats

컨테이너 접속

# 백엔드 컨테이너 셸 접속
docker-compose exec backend /bin/bash

# 프론트엔드 컨테이너 셸 접속
docker-compose exec frontend /bin/bash

# Python 인터프리터 실행
docker-compose exec backend python

# 명령어 실행
docker-compose exec backend ls -la

이미지 관리

# 이미지 재빌드 (캐시 무시)
docker-compose build --no-cache

# 특정 서비스만 빌드
docker-compose build backend

# 이미지 목록 확인
docker images

# 사용하지 않는 이미지 삭제
docker image prune -a

Makefile 사용

프로젝트에 포함된 Makefile을 사용하면 더 간편하게 Docker를 관리할 수 있습니다.

사용 가능한 명령어

# 도움말 보기
make help

# 이미지 빌드
make build

# 프로덕션 모드 시작
make up
# 또는
make prod

# 개발 모드 시작 (코드 자동 반영)
make dev

# 컨테이너 중지
make down

# 컨테이너 재시작
make restart

# 로그 확인
make logs

# 백엔드 로그
make logs-backend

# 프론트엔드 로그
make logs-frontend

# 컨테이너 상태
make ps

# 모든 것 삭제 (주의!)
make clean

# 백엔드 셸 접속
make shell-backend

# 프론트엔드 셸 접속
make shell-frontend

예시 워크플로우

# 1. 프로젝트 시작
make build
make up

# 2. 로그 확인
make logs

# 3. 개발 중 재시작이 필요할 때
make restart

# 4. 종료
make down

# 5. 완전히 정리 (주의: 모든 데이터 삭제)
make clean

개발 모드 vs 프로덕션 모드

프로덕션 모드 (기본)

# docker-compose.yml 사용
docker-compose up
# 또는
make prod

특징:

  • 최적화된 이미지
  • 코드가 컨테이너에 복사됨
  • 코드 변경 시 재빌드 필요
  • 안정적인 운영 환경

개발 모드

# docker-compose.dev.yml 사용
docker-compose -f docker-compose.dev.yml up
# 또는
make dev

특징:

  • 볼륨 마운트로 코드 자동 반영
  • Hot-reload 지원
  • 빠른 개발 사이클
  • 디버깅 용이

개발 모드에서 코드 변경:

  1. 로컬에서 코드 수정
  2. 저장하면 자동으로 서버 재시작
  3. 브라우저 새로고침하여 확인

네트워크 구성

네트워크 구조

┌─────────────────────────────────────┐
│     fastapi_streamlit_network       │
│                                     │
│  ┌──────────────┐  ┌─────────────┐ │
│  │   backend    │  │  frontend   │ │
│  │  (FastAPI)   │◄─┤ (Streamlit) │ │
│  │   :8000      │  │   :8501     │ │
│  └──────┬───────┘  └──────┬──────┘ │
│         │                 │         │
└─────────┼─────────────────┼─────────┘
          │                 │
    localhost:8000   localhost:8501

컨테이너 간 통신

프론트엔드에서 백엔드 접근:

# 컨테이너 내부에서
API_URL = "http://backend:8000"

# 호스트에서
API_URL = "http://localhost:8000"

네트워크 명령어

# 네트워크 목록 확인
docker network ls

# 네트워크 상세 정보
docker network inspect fastapi_streamlit_network

# 네트워크 재생성
docker-compose down
docker network prune
docker-compose up

트러블슈팅

1. 포트가 이미 사용 중

문제:

Error starting userland proxy: listen tcp4 0.0.0.0:8000: bind: address already in use

해결:

# Mac/Linux
lsof -ti:8000 | xargs kill -9
lsof -ti:8501 | xargs kill -9

# Windows (PowerShell)
Get-Process -Id (Get-NetTCPConnection -LocalPort 8000).OwningProcess | Stop-Process -Force

또는 docker-compose.yml에서 포트 변경:

ports:
  - "8001:8000"  # 호스트:컨테이너

2. 이미지 빌드 실패

문제: 의존성 설치 중 오류

해결:

# 캐시 없이 재빌드
docker-compose build --no-cache

# Python 버전 확인 (Dockerfile)
# FROM python:3.11-slim

# requirements.txt 버전 확인

3. 컨테이너가 계속 재시작됨

문제: 컨테이너 상태가 Restarting

해결:

# 로그 확인
docker-compose logs backend

# 헬스체크 문제일 수 있음
# docker-compose.yml에서 헬스체크 일시 비활성화

4. 백엔드에 연결할 수 없음

문제: 프론트엔드에서 "API 서버에 연결할 수 없습니다"

해결:

# 1. 백엔드 컨테이너 상태 확인
docker-compose ps

# 2. 백엔드 로그 확인
docker-compose logs backend

# 3. 네트워크 확인
docker network inspect fastapi_streamlit_network

# 4. 환경 변수 확인
docker-compose exec frontend env | grep API

# 5. 헬스체크 대기
# depends_on: service_healthy가 설정되어 있으면
# 백엔드가 준비될 때까지 기다림

5. 코드 변경이 반영되지 않음

문제: 코드를 수정했는데 변경사항이 보이지 않음

해결:

# 프로덕션 모드: 재빌드 필요
docker-compose down
docker-compose up --build

# 개발 모드 사용 (권장)
docker-compose -f docker-compose.dev.yml up

6. 메모리 부족

문제: Docker 메모리 제한

해결:

# Docker Desktop 설정에서 메모리 증가
# Settings > Resources > Memory

# 또는 docker-compose.yml에서 제한 설정
services:
  backend:
    deploy:
      resources:
        limits:
          memory: 512M

7. 볼륨 데이터 문제

문제: 데이터가 남아있거나 꼬임

해결:

# 볼륨 포함 완전 삭제
docker-compose down -v

# 모든 볼륨 삭제 (주의!)
docker volume prune

# 특정 볼륨만 삭제
docker volume rm <volume_name>

8. 네트워크 충돌

문제: 네트워크 생성 실패

해결:

# 기존 네트워크 삭제
docker network rm fastapi_streamlit_network

# 사용하지 않는 네트워크 정리
docker network prune

유용한 팁

1. 로그 실시간 모니터링

# 터미널 분할하여 각각 모니터링
# 터미널 1
docker-compose logs -f backend

# 터미널 2
docker-compose logs -f frontend

2. 컨테이너 내부 파일 확인

# 파일 구조 확인
docker-compose exec backend ls -la

# 특정 파일 내용 보기
docker-compose exec backend cat main.py

# 파일 복사 (컨테이너 -> 호스트)
docker cp fastapi_backend:/app/main.py ./main_backup.py

3. 데이터베이스 추가

docker-compose.yml에 추가:

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
      POSTGRES_DB: mydb
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - app_network

volumes:
  postgres_data:

4. 환경 변수 파일 사용

.env 파일 생성:

BACKEND_PORT=8000
FRONTEND_PORT=8501

docker-compose.yml에서 사용:

services:
  backend:
    ports:
      - "${BACKEND_PORT}:8000"

5. 프로덕션 최적화

# 멀티 스테이지 빌드
FROM python:3.11-slim as builder
WORKDIR /app
COPY requirements.txt .
RUN pip wheel --no-cache-dir --no-deps --wheel-dir /app/wheels -r requirements.txt

FROM python:3.11-slim
WORKDIR /app
COPY --from=builder /app/wheels /wheels
RUN pip install --no-cache /wheels/*
COPY . .
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

참고 자료

문제가 해결되지 않으면 이슈를 등록해주세요! 🐛