Cursor Docker 개발: 컨테이너 기반 워크플로우 간소화

Docker는 일관된 개발 환경을 위해 필수가 되었으며, Cursor의 AI 기능을 통해 컨테이너 작업을 더 빠르고 직관적으로 만들 수 있습니다. 이 가이드에서는 Dockerfile 생성, Docker Compose 오케스트레이션, Dev Containers, 디버깅 워크플로우를 다룹니다.

사전 요구 사항

시작하기 전에 다음이 필요합니다:

• 머신에 설치 및 실행 중인 Docker
• Cursor (최신 버전 권장)
• Docker 개념(이미지, 컨테이너, 볼륨)에 대한 기본적인 이해

Cursor로 Dockerfile 생성하기

프로덕션용 Dockerfile 생성

애플리케이션 스택을 설명하고 Cursor가 최적화된 Dockerfile을 생성하도록 하세요:

다음 조건을 만족하는 Next.js 14 애플리케이션용 다단계 Dockerfile을 생성해주세요:
- Node.js 20 Alpine 사용
- npm ci로 의존성 설치
- 프로덕션 번들 빌드
- 비루트 사용자로 실행
- 최소한의 최종 이미지 사용

Cursor가 생성한 결과:

# Build stage
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Production stage
FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production

# Create non-root user
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs
EXPOSE 3000
ENV PORT=3000
ENV HOSTNAME="0.0.0.0"

CMD ["node", "server.js"]

기존 Dockerfile 최적화

Dockerfile을 붙여넣고 개선 사항을 요청하세요:

더 빠른 빌드와 더 작은 이미지 크기를 위해 이 Dockerfile을 최적화해주세요:
[Dockerfile 붙여넣기]

Cursor가 제안하는 일반적인 최적화:

• 레이어를 줄이기 위해 RUN 명령어 결합
• 컨텍스트를 최소화하기 위해 .dockerignore 사용
• 빌드 캐시를 효과적으로 활용
• latest 대신 특정 기본 이미지 태그 사용

.dockerignore 모범 사례

node_modules
npm-debug.log
Dockerfile
.dockerignore
.git
.gitignore
README.md
.env
.env.local
.env.production
.nyc_output
coverage
.vscode
.idea

Docker Compose 개발 스택

풀스택 애플리케이션 설정

version: '3.8'
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/myapp
      - REDIS_URL=redis://redis:6379
    volumes:
      - .:/app
      - /app/node_modules
    depends_on:
      - db
      - redis

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: myapp
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - app

volumes:
  postgres_data:

핫 리로드 설정

라이브 리로딩이 포함된 개발 환경:

services:
  dev:
    build:
      context: .
      target: builder
    command: npm run dev
    ports:
      - "3000:3000"
    volumes:
      - .:/app
      - /app/node_modules
    environment:
      - CHOKIDAR_USEPOLLING=true
      - WATCHPACK_POLLING=true

볼륨 트릭

소스 코드는 - .:/app으로 마운트하지만 node_modules는 - /app/node_modules로 제외하세요. 이렇게 하면 컨테이너와 호스트의 node_modules가 충돌하는 것을 방지할 수 있습니다.

Cursor의 Dev Containers

.devcontainer 설정

.devcontainer/devcontainer.json 생성:

{
  "name": "Node.js & PostgreSQL",
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspace",
  "features": {
    "ghcr.io/devcontainers/features/node:1": {
      "version": "20"
    },
    "ghcr.io/devcontainers/features/git:1": {}
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "Prisma.prisma",
        "esbenp.prettier-vscode",
        "dbaeumer.vscode-eslint"
      ],
      "settings": {
        "terminal.integrated.defaultProfile.linux": "bash"
      }
    }
  },
  "postCreateCommand": "npm install",
  "forwardPorts": [3000, 5432],
  "remoteUser": "node"
}

Dev Container Docker Compose

version: '3.8'
services:
  app:
    image: mcr.microsoft.com/devcontainers/javascript-node:20
    volumes:
      - ..:/workspace:cached
    command: sleep infinity
    network_mode: service:db

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: dev
      POSTGRES_DB: workspace
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  postgres-data:

Dev Container 열기

1. Cursor에서 F1 누르기
2. Dev Containers: Reopen in Container 선택
3. Cursor가 컨테이너를 빌드하고 워크스페이스를 내부에서 다시 엽니다

첫 빌드

초기 컨테이너 빌드는 몇 분이 소요될 수 있습니다. 이후 재빌드는 Docker 캐시를 사용하여 훨씬 빠릅니다.

컨테이너 내부 디버깅

Node.js 디버깅

Docker Compose에 추가:

services:
  app:
    build: .
    ports:
      - "3000:3000"
      - "9229:9229"  # Debug port
    command: node --inspect=0.0.0.0:9229 index.js

Cursor launch.json 구성:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Docker: Attach to Node",
      "type": "node",
      "request": "attach",
      "port": 9229,
      "address": "localhost",
      "localRoot": "${workspaceFolder}",
      "remoteRoot": "/app",
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

컨테이너 내부 Python 디버깅

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "-m", "debugpy", "--listen", "0.0.0.0:5678", "--wait-for-client", "app.py"]

일반적인 Docker 워크플로우

빌드 및 실행

# Build image
docker build -t myapp:latest .

# Run container
docker run -p 3000:3000 --env-file .env myapp:latest

# Run with volume mount
docker run -p 3000:3000 -v $(pwd):/app myapp:latest

데이터베이스 마이그레이션

# Run migrations in container
docker-compose exec app npx prisma migrate deploy

# Seed database
docker-compose exec app npx prisma db seed

로그 보기

# Follow all logs
docker-compose logs -f

# Specific service
docker-compose logs -f app

# Last 100 lines
docker-compose logs --tail=100 app

Docker 명령어 빠른 참고

명령어	설명
docker ps	실행 중인 컨테이너 목록
docker images	로컬 이미지 목록
docker-compose up -d	백그라운드에서 서비스 시작
docker-compose down	컨테이너 중지 및 제거
docker-compose build	이미지 재빌드
docker exec -it <container> sh	실행 중인 컨테이너에 셸 접속
docker logs -f <container>	컨테이너 로그 팔로우
docker system prune	미사용 리소스 정리

Cursor로 문제 해결

컨테이너가 시작되지 않음

Dockerfile과 오류 로그를 공유하세요:

이 컨테이너가 코드 1로 즉시 종료됩니다. Dockerfile과 로그는 다음과 같습니다:
[내용 붙여넣기]

포트 충돌

Error: bind EADDRINUSE :::3000

Cursor는 호스트 포트 가용성을 확인하고 포트 매핑을 수정하도록 제안합니다.

권한 문제

볼륨 권한 문제에 대한 일반적인 수정:

# Add to Dockerfile
RUN chown -R node:node /app
USER node

다중 환경 구성

project/
  docker/
    Dockerfile.dev
    Dockerfile.prod
  docker-compose.yml
  docker-compose.prod.yml
  docker-compose.override.yml

프로덕션 Compose

version: '3.8'
services:
  app:
    build:
      context: ..
      dockerfile: docker/Dockerfile.prod
    restart: always
    deploy:
      replicas: 3
      resources:
        limits:
          cpus: '1'
          memory: 512M

AI 기반 Dockerfile 검토

Cursor에게 설정을 감사하도록 요청하세요:

이 Docker 설정을 다음 관점에서 검토해주세요:
1. 보안 모범 사례
2. 이미지 크기 최적화
3. 빌드 캐시 효율성
4. 적절한 신호 처리 (PID 1)
5. 헬스 체크

관련 리소스

• Cursor 데이터베이스 개발 가이드
• Cursor API 개발 가이드
• Cursor 백그라운드 에이전트 가이드

마지막 업데이트: 2025년 7월