Cycle 5: Runtime 환경

개발 환경의 중요성

"내 컴퓨터에서는 되는데..."라는 말을 없애려면 모든 개발자가 동일한 환경에서 작업해야 합니다.

환경이 다르면

Node.js 버전 차이로 빌드 실패
DB 버전 차이로 쿼리 오류
OS 차이로 경로 문제 발생

환경이 같으면

새 팀원도 바로 개발 시작
버그 재현이 쉬움
CI/CD와 동일한 환경

docker-compose 활용

docker-compose는 여러 컨테이너를 한 번에 관리하는 도구입니다. 프론트엔드, 백엔드, 데이터베이스를 모두 정의할 수 있습니다.

기본 구성

docker-compose.yml

services:
  # Frontend (React)
  frontend:
    build: ./frontend
    ports:
      - "3000:3000"
    volumes:
      - ./frontend:/app
      - /app/node_modules
    environment:
      - VITE_API_URL=http://localhost:8080

  # Backend (FastAPI)
  backend:
    build: ./backend
    ports:
      - "8080:8080"
    volumes:
      - ./backend:/app
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/myapp
    depends_on:
      - db

  # Database (PostgreSQL)
  db:
    image: postgres:15
    ports:
      - "5432:5432"
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass
      - POSTGRES_DB=myapp
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

자주 쓰는 명령어

터미널

# 모든 서비스 시작
docker-compose up

# 백그라운드로 시작
docker-compose up -d

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

# 로그 확인
docker-compose logs -f backend

# 모든 서비스 중지 및 삭제
docker-compose down

# 볼륨까지 삭제 (주의!)
docker-compose down -v

핫 리로드 설정

개발 중 코드 변경이 즉시 반영되도록 볼륨을 마운트합니다.

Dockerfile (개발용)

# FastAPI 개발 서버 (핫 리로드 활성화)
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080", "--reload"]

환경별 설정 분리

.env 파일 관리

.env 파일들

# .env.development (로컬 개발)
DATABASE_URL=postgresql://user:pass@localhost:5432/myapp_dev
DEBUG=true
API_URL=http://localhost:8080

# .env.staging (스테이징)
DATABASE_URL=postgresql://user:pass@staging-db:5432/myapp_staging
DEBUG=true
API_URL=https://staging-api.myapp.com

# .env.production (프로덕션)
DATABASE_URL=postgresql://user:pass@prod-db:5432/myapp
DEBUG=false
API_URL=https://api.myapp.com

.gitignore에 추가

.env 파일은 절대 Git에 커밋하지 마세요. 대신 .env.example을 만들어 템플릿을 공유합니다.

.env.example 예시

.env.example

# 데이터베이스
DATABASE_URL=postgresql://user:password@host:5432/dbname

# API 설정
API_URL=https://api.example.com
DEBUG=false

# 인증
JWT_SECRET=your-secret-key-here

클라우드 vs 로컬

상황	추천	이유
혼자 개발	docker-compose	무료, 빠른 피드백
팀 개발	클라우드 DB + 로컬 앱	데이터 공유 필요
스테이징	클라우드	실제 환경과 유사
프로덕션	클라우드	안정성, 확장성

비용 최적화 팁

개발 시간에만 클라우드 DB 사용 (사용량 기반 과금)
무료 티어 적극 활용 (Supabase, Neon, PlanetScale)
스테이징 환경은 최소 사양으로 유지
로컬 DB로 충분한 테스트 후 클라우드 배포

심화 문서

멀티 환경 운영

development/staging/production 분리 운영 가이드

환경변수 점검 레시피

누락/오탈자/노출 위험 빠른 점검

다음 단계

개발 환경 구성이 완료되었다면, 이제 운영에 대해 배워봅시다. Cycle 6: Ops에서 배포 전략, 모니터링, 비용 관리를 배웁니다.