본문으로 건너뛰기

Docker 개발 환경

개발 환경을 위한 Docker 설정 가이드입니다.

📝 초안 (Draft)

이 문서는 검토 중입니다. 내용이 변경될 수 있습니다.

개요​

Foundation은 Docker를 통해 일관된 개발 환경을 제공합니다. 이 문서는 개발 환경 설정에 초점을 맞춥니다.

운영 환경 Docker

운영/배포 관련 Docker 설정은 인프라 운영 > Docker를 참조하세요.

개발 vs 운영​

구분개발 환경운영 환경
목적빠른 피드백, 디버깅안정성, 성능
볼륨소스 코드 마운트이미지에 포함
로깅상세 로그최소 로그
설정디버그 모드프로덕션 모드

개발 환경 설정​

소스 코드 마운트​

# docker-compose.yml (개발용)
services:
  app:
    volumes:
      # 소스 코드 실시간 반영
      - ./web:/var/www/html
      # 의존성은 별도 볼륨 (성능)
      - app_vendor:/var/www/html/vendor

volumes:
  app_vendor:

디버그 설정​

services:
  app:
    environment:
      - APP_DEBUG=true
      - XDEBUG_MODE=debug
      - XDEBUG_CONFIG=client_host=host.docker.internal

유용한 개발 명령어​

컨테이너 접속​

# 앱 컨테이너 셸 접속
make shell NAME=myproject

# 또는 직접
docker exec -it myproject-web bash

로그 확인​

# 실시간 로그
make logs NAME=myproject

# 특정 서비스 로그
docker compose logs -f web

재시작​

# 앱만 재시작 (빠름)
make restart NAME=myproject

# 전체 재시작
make down NAME=myproject && make up NAME=myproject

성능 최적화​

볼륨 성능 (macOS)​

macOS에서 Docker 볼륨 성능 개선:

volumes:
  - ./web:/var/www/html:cached
  # 또는
  - ./web:/var/www/html:delegated

불필요한 파일 제외​

# .dockerignore
node_modules
vendor
.git
*.log

일반적인 문제​

권한 문제​

# 컨테이너 내부 사용자 확인
docker exec myproject-web id

# 호스트와 동일한 UID 사용
# docker-compose.yml에서:
user: "${UID}:${GID}"

포트 충돌​

# 사용 중인 포트 확인
lsof -i :8080

# 포트 변경 (.env)
APP_PORT=8081

캐시 문제​

# 이미지 재빌드
docker compose build --no-cache

# 볼륨 초기화 (주의: 데이터 삭제)
docker compose down -v

IDE 연동​

VS Code Remote Containers​

// .devcontainer/devcontainer.json
{
  "name": "Dev Container",
  "dockerComposeFile": "../docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/var/www/html"
}

PHPStorm Docker 연동​

  1. Settings → PHP → CLI Interpreter → Docker 선택
  2. Docker Compose 서비스 지정
  3. Path mappings 설정

관련 문서​