VS Code에 Docker 통합하기: 설정, 빌드, 실행 가이드

중요: 이 문서는 Docker Desktop(또는 Docker 엔진)이 이미 설치되어 있고 VS Code가 동작하는 환경을 전제로 합니다. WSL2 또는 원격 Docker 호스트를 사용하는 경우 추가 설정이 필요할 수 있습니다.

주목할 검색 의도

• 기본 목적: VS Code에서 Docker 통합 설정 방법 안내
• 관련 변형: Docker 확장 설치, Dockerfile 자동 생성, 이미지 빌드/실행, 컨테이너 관리, 문제 해결

설치 전 확인 사항

• Docker Desktop(또는 Docker 엔진)이 설치되어 있고 작동하는지 확인하세요.
• VS Code 최신 버전을 권장합니다.
• 필요한 경우 WSL2 통합 또는 원격 Docker 호스트 접속 정보를 준비하세요.

VS Code에 Docker 확장 설치

1. VS Code에서 확장(Extensions) 보기로 이동합니다.
2. 검색창에 “Docker”를 입력하고 Microsoft의 공식 Docker 확장을 설치하세요.

설치가 완료되면 에디터 왼쪽 하단에 Docker/Containers 로고가 나타납니다. 이 아이콘이 Docker Explorer를 엽니다.

중요: 확장이 설치되어도 Docker 엔진이 실행 중이 아니라면 연결되지 않습니다. Docker Desktop을 시작했는지 확인하세요.

Docker Desktop과 VS Code 연결 확인

Docker Desktop이 실행 중일 때 VS Code는 자동으로 Docker 데몬에 연결합니다. 원격 호스트나 특수 구성(예: TLS, 비표준 소켓)이 필요한 경우 수동 구성이 필요합니다.

1. 왼쪽 사이드바의 Docker 아이콘을 클릭해 Docker Explorer를 엽니다.
2. CONTAINERS, IMAGES, REGISTRIES, VOLUMES, NETWORKS 등을 확인합니다.

VS Code에서 컨테이너·이미지·볼륨 관리하기

Docker 확장이 통합되면 VS Code 내에서 다음 작업을 수행할 수 있습니다:

• 실행 중인 컨테이너와 중지된 컨테이너 보기
• 컨테이너 우클릭으로 시작·중지·재시작·삭제
• 이미지 풀(pull), 빌드(build), 제거(remove)
• 볼륨 검사 및 관리
• 네트워크와 컨텍스트 전환

이미지를 우클릭해 Remove를 선택하면 불필요한 이미지를 즉시 삭제할 수 있습니다.

볼륨을 우클릭하면 볼륨 내용 확인과 같은 관리 작업을 할 수 있습니다.

또한 레지스트리 로그인, 컨텍스트 전환, 도움말 및 피드백 접근 기능을 통해 워크플로우를 간소화할 수 있습니다.

VS Code에서 컨테이너화된 앱 빌드 및 실행

아래 예시는 간단한 Node.js Express 앱을 Docker로 빌드하고 실행하는 전체 흐름을 보여줍니다.

1. 새 프로젝트 폴더를 만들고 index.js 파일을 생성합니다.

const express = require("express");  
const server = express();  
const PORT = 4000;  
  
server.get("/", (req, res) => {  
  res.send("Welcome to our Express app!");  
});  
  
server.listen(PORT, () => {  
  console.log(`App running on port ${PORT}`);  
});

이 코드는 포트 4000에서 동작하는 간단한 Express 앱을 만듭니다. 루트 경로(/)로 접속하면 환영 메시지가 출력됩니다.

2. Command Palette(단축키: Mac ⌘⇧P, Windows Ctrl+Shift+P)를 열고 Add Docker files to Workspace 명령을 실행합니다.

3. 플랫폼으로 Node.js를 선택하고, package.json 파일(프로젝트 루트)을 지정합니다. 확장은 Dockerfile, .dockerignore, 선택 시 compose.yaml을 생성합니다.

포트를 지정하고 Docker Compose 포함 여부를 묻는 옵션에 “Yes”를 선택하면 필요한 파일들이 생성됩니다.

4. 생성된 Dockerfile을 우클릭하고 Build Image를 선택하거나, Command Palette에서 Docker Images: Build Image를 실행해 이미지를 빌드합니다.

빌드가 완료되면 이미지 목록에서 생성된 이미지를 확인합니다.

5. Docker Explorer의 Images 항목에서 해당 이미지를 우클릭하여 Run을 선택하거나 Command Palette에서 Container Images: Run 명령을 실행합니다.

이미지 목록에서 최신 이미지를 선택하면 컨테이너가 생성·실행됩니다.

6. Docker Explorer의 Containers 섹션에서 실행 중인 컨테이너를 확인하고, 우클릭해 Open in Browser를 선택하면 애플리케이션을 브라우저에서 확인할 수 있습니다.

로그 출력과 터미널로 진입해 문제를 확인할 수도 있습니다.

빠른 체크리스트

• 설치자(Developer):

  • VS Code에서 Docker 확장 설치
  • package.json과 index.js가 프로젝트 루트에 있는지 확인
  • Command Palette로 Docker 파일 생성
  • 이미지 빌드 및 실행 후 로그 확인

• 운영/DevOps:

  • Docker Desktop 업데이트 및 리소스(메모리/CPU) 설정
  • WSL2 통합 또는 원격 Docker 소켓 인증 구성
  • 이미지 레지스트리 정책(태그/보안) 적용

• QA/테스터:

  • 컨테이너 시작 시 헬스체크 동작 확인
  • 포트 매핑 및 외부 접근성 테스트
  • 볼륨을 통한 데이터 지속성 검증

문제 해결 런북 (간단)

1. Docker 확장이 동작하지 않을 때

   • Docker Desktop이 실행 중인지 확인
   • VS Code를 재시작하거나 확장을 재설치
   • 원격 Docker를 사용하는 경우 DOCKER_HOST/DOCKER_CERT_PATH 환경변수 확인

2. 이미지 빌드 실패

   • Dockerfile의 베이스 이미지와 명령문을 검토
   • 빌드 로그에서 오류 메시지(권한, 파일 없음 등) 확인
   • 네트워크 문제 시 –network=host 또는 프록시 설정 검토

3. 컨테이너가 바로 종료될 때

   • 컨테이너 로그 확인: 우클릭 > View Logs
   • 앱이 포트 바인딩을 제대로 했는지 확인
   • CMD/ENTRYPOINT 오류 여부 검사

명령 모음(Cheat sheet)

# 빌드
docker build -t my-app:latest .
# 실행 (포트 매핑)
docker run -d -p 4000:4000 --name my-app my-app:latest
# 이미지 목록
docker images
# 컨테이너 목록
docker ps -a
# 로그 보기
docker logs -f my-app
# 컨테이너 삭제
docker rm my-app
# 이미지 삭제
docker rmi my-app:latest
# compose로 실행
docker-compose up -d

VS Code 관련 빠른 명령:

• Add Docker files to Workspace
• Docker Images: Build Image
• Containers: Open in Browser
• Docker: Show Logs

대안 및 언제 통합이 실패하는가

대안:

• Dev Containers 확장(개발 환경 격리) — 개발 환경을 코딩 컨테이너로 표준화할 때 유용
• Remote - Containers(Remote Development) — 코드를 컨테이너 내부에서 직접 편집해야 할 때
• Podman — Docker와 유사하지만 무데몬(daemonless) 옵션을 원할 때

통합이 실패하는 전형적 상황:

• 로컬 Docker 데몬 접근 권한이 없거나, 보안 정책으로 소켓 접근이 차단된 경우
• WSL2와의 통합 문제(네트워크/파일 권한)로 인해 파일이 마운트되지 않는 경우
• VS Code 확장 버전과 Docker Desktop 버전 간의 비호환성

머리 속 모델(mental model)

• VS Code의 Docker 확장은 로컬 Docker API에 대한 UI 래퍼입니다. 실제 빌드·실행은 기존 Docker 엔진이 수행합니다.
• 확장은 파일 생성과 명령 실행을 자동화해 개발 경험을 줄여주지만, 이미지 최적화와 보안 설정은 직접 관리해야 합니다.

검수 기준

• 컨테이너가 정상적으로 실행되고 애플리케이션의 루트 경로에서 기대하는 응답을 반환한다.
• 이미지가 생성되어 Images 목록에 표시된다.
• 필요한 포트(예: 4000)가 호스트와 컨테이너 양쪽에서 올바르게 매핑된다.
• 로그와 터미널에 접근할 수 있다.

간단한 플레이북(신규 프로젝트용)

1. 프로젝트 루트에 package.json과 소스 파일 준비
2. VS Code에서 “Add Docker files to Workspace” 실행
3. Dockerfile 생성 옵션 선택 및 포트 지정
4. Dockerfile 우클릭 → Build Image
5. 생성된 이미지 Run → 컨테이너 실행 확인
6. 브라우저로 접속해 기능 점검

보안 및 개인정보 주의

• 이미지에 민감한 정보를 하드코딩하지 마세요. 환경 변수나 시크릿 매니저를 사용하세요.
• 빌드 시 캐시나 레이어에 비밀번호가 남지 않도록 주의하세요.

요약

VS Code에 Docker를 통합하면 개발자가 에디터에서 떠나지 않고도 컨테이너화된 애플리케이션을 만들고 관리할 수 있습니다. Docker 확장은 Dockerfile 생성, 이미지 빌드, 컨테이너 실행 및 로그 확인을 간소화합니다. 운영 정책, 보안, 리소스 제약을 고려해 통합을 진행하세요.

핵심 포인트:

• Docker Desktop이 필요합니다.
• VS Code의 Docker 확장이 Docker API를 통해 작업을 수행합니다.
• 자동 생성된 Dockerfile을 확인하고 필요 시 최적화하세요.

짧은 체크리스트(요약형)

• Docker Desktop 실행 확인
• VS Code에 Docker 확장 설치
• Add Docker files to Workspace로 파일 생성
• 이미지 빌드 및 컨테이너 실행
• 브라우저에서 앱 접근 확인