[Hot Item] #3. Dev Container로 VS Code 개발 환경 컨테이너 안으로 옮기기

Hot Item

[Hot Item] #3. Dev Container로 VS Code 개발 환경 컨테이너 안으로 옮기기

devjingood 2026. 3. 6. 15:05

시리즈: Hot Item 프로젝트 구축기
태그: Docker Dev Container VSCode docker-compose

이 글에서 다루는 내용

Dev Container가 무엇이고 왜 사용하는지
VS Code에서 Dev Container 확장 설치하기
.devcontainer 폴더 생성 및 devcontainer.json 작성하기
.gitignore 처리 및 Rebuild로 개발 환경 완성하기

1. Dev Container란?

지금까지 Django, PostgreSQL, Redis를 모두 컨테이너 안에서 실행하도록 구성했습니다. 그런데 VS Code는 여전히 로컬에서 실행되고 있습니다.

이 상태에서는 VS Code의 자동완성이나 타입 힌트 같은 기능이 제대로 동작하지 않을 수 있습니다. VS Code가 바라보는 Python은 로컬의 Python이고, 실제 코드가 실행되는 Python은 컨테이너 안에 있기 때문입니다.

Dev Container는 이 간격을 없애줍니다. VS Code 자체를 컨테이너 안으로 들어가서 작동하게 만드는 기능입니다. 에디터, 자동완성, 터미널까지 모두 컨테이너 환경을 기준으로 동작하게 됩니다.

[ 기존 ]
VS Code (로컬 Python 바라봄) ←→ Docker 컨테이너 (실제 실행 환경)
                          ↑ 환경 불일치 발생 가능

[ Dev Container 적용 후 ]
VS Code ──────────────────────────────────────────────────────
                         컨테이너 안                          │
         에디터 + 자동완성 + 터미널 모두 컨테이너 기준으로 동작 │
──────────────────────────────────────────────────────────────

2. VS Code 확장 설치하기

VS Code의 확장(Extension) 탭에서 Dev Containers를 검색해 설치합니다.

설치가 완료되면 VS Code 왼쪽 하단에 >< 모양의 초록색 아이콘이 생깁니다.

3. .devcontainer 폴더 생성하기

Dev Container 설정 파일은 프로젝트 루트에 .devcontainer 폴더를 만들고 그 안에 넣습니다.

VS Code 커맨드 팔레트(Cmd+Shift+P)를 열고 아래를 선택합니다.

Dev Containers: Reopen in Container

그러면 VS Code가 자동으로 프로젝트 루트에 .devcontainer 폴더와 기본 devcontainer.json 파일을 생성합니다. 우리는 이 파일의 내용을 직접 수정해서 사용합니다.

💡 왜 루트에 있나요?
Dev Container는 프로젝트의 어떤 docker-compose.yml을 참조할지 경로를 직접 지정하기 때문에, 프로젝트 구조를 한눈에 파악할 수 있는 루트에 두는 것이 일반적입니다.

4. .gitignore에 .devcontainer 추가하기

.devcontainer 폴더는 개발자 개인의 에디터 환경 설정입니다. 팀원마다 쓰는 에디터가 다를 수 있고, 개인 환경 설정이 저장소에 포함될 필요가 없으므로 .gitignore에 추가합니다.

# 환경 변수 (절대 올리면 안 됨)
.env

# Dev Container (개인 에디터 설정)
.devcontainer/

# Python
__pycache__/
*.pyc
*.pyo
.pytest_cache/

# Django
*.log
db.sqlite3

5. devcontainer.json 작성하기

.devcontainer/devcontainer.json 파일을 아래와 같이 작성합니다.

{
    "name": "Hot Item Workspace",
    "dockerComposeFile": [
        "../docker-compose.yml",
        "docker-compose.yml"
    ],
    "service": "web",
    "workspaceFolder": "/app",
    "customizations": {
        "vscode": {
            "settings": {
                "python.defaultInterpreterPath": "/usr/local/bin/python"
            },
            "extensions": [
                "ms-python.python",
                "ms-python.vscode-pylance",
                "batisteo.vscode-django"
            ]
        }
    }
}

각 항목의 의미를 살펴봅니다.

name
Dev Container의 이름입니다. VS Code 왼쪽 하단에 표시됩니다.

dockerComposeFile
참조할 docker-compose.yml 파일 목록입니다. 배열로 여러 파일을 지정할 수 있으며, 나중에 명시된 파일이 앞 파일의 설정을 덮어씁니다.

"../docker-compose.yml": 프로젝트 루트의 기존 docker-compose.yml (서비스 정의)
"docker-compose.yml": .devcontainer/docker-compose.yml (Dev Container 전용 설정, 이 파일은 다음 단계에서 만듭니다)

service
VS Code가 접속할 서비스를 지정합니다. web으로 설정했으므로 VS Code는 Django 컨테이너 안으로 들어갑니다.

workspaceFolder
VS Code가 열 컨테이너 내부의 작업 폴더 경로입니다. Dockerfile의 WORKDIR /app과 일치시킵니다.

customizations.vscode
컨테이너 안에서 VS Code에 자동으로 적용될 설정과 확장 목록입니다.

python.defaultInterpreterPath: VS Code가 사용할 Python 인터프리터 경로를 컨테이너 안의 Python으로 명시적으로 지정합니다.
ms-python.python: Python 기본 확장
ms-python.vscode-pylance: 강력한 타입 힌트 및 자동완성 기능
batisteo.vscode-django: Django 템플릿 문법 지원 및 Django 관련 자동완성

6. .devcontainer/docker-compose.yml 만들기

devcontainer.json이 두 번째로 참조하는 .devcontainer/docker-compose.yml을 만듭니다. 이 파일은 Dev Container 전용으로 web 서비스에 필요한 추가 설정을 덮어씁니다.

touch .devcontainer/docker-compose.yml
nano .devcontainer/docker-compose.yml

services:
  web:
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

💡 /var/run/docker.sock이 무엇인가요?
Docker 데몬(실제 컨테이너를 실행하는 엔진)과 통신하는 소켓 파일입니다. 이것을 컨테이너 안에 마운트하면, 컨테이너 내부의 터미널에서도 docker 명령어를 사용할 수 있습니다. 컨테이너 안에서 컨테이너를 다루는 환경(Docker-in-Docker 방식)이 됩니다.

7. Rebuild하여 Dev Container 실행하기

모든 파일이 준비됐다면 이제 Dev Container를 실행합니다.

커맨드 팔레트(Cmd+Shift+P)를 열고:

Dev Containers: Rebuild and Reopen in Container

을 선택합니다. VS Code가 이미지를 빌드하고 컨테이너에 접속합니다. 완료되면 VS Code 왼쪽 하단이 아래처럼 바뀝니다.

>< Dev Container: Hot Item Workspace

이제 VS Code의 터미널을 열면(Ctrl+`` ``), 로컬이 아닌 컨테이너 내부 터미널이 열립니다.

# 터미널에서 확인
which python
# /usr/local/bin/python  ← 컨테이너 안의 Python

python --version
# Python 3.12.x

이 상태에서 Django 명령어를 실행하면 로컬에 Python이 없어도 정상 동작합니다.

8. 최종 폴더 구조

hot-item/
├── .devcontainer/                  # Dev Container 설정 (Git 제외)
│   ├── devcontainer.json
│   └── docker-compose.yml
├── config/                         # Django 프로젝트 설정 폴더
│   ├── __init__.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── .env                            # 환경 변수 (Git 제외)
├── .gitignore
├── Dockerfile
├── docker-compose.yml
├── manage.py
└── requirements.txt

9. 정리

오늘 한 작업을 요약하면:

Dev Container를 사용해 VS Code 자체를 컨테이너 안으로 옮겨, 로컬과 컨테이너 간 환경 불일치 문제를 해결했습니다.
devcontainer.json에서 참조할 docker-compose 파일, 접속할 서비스, VS Code 설정과 확장을 정의했습니다.
.devcontainer 폴더는 개인 에디터 설정이므로 .gitignore에 추가해 저장소에 포함되지 않도록 처리했습니다.
Rebuild and Reopen in Container로 컨테이너 기반 개발 환경을 완성했습니다.