원격 Docker 호스트에서 개발

때로는 원격 서버에 있는 컨테이너 안에서 개발하기 위해 Dev Containers 확장을 사용하고 싶을 수 있습니다. Docker는 로컬 파일 시스템을 원격 개발 컨테이너로 마운트(바인딩)하는 것을 지원하지 않으므로, Visual Studio Code의 기본 devcontainer.json 동작인 로컬 소스 코드를 사용하는 것은 작동하지 않습니다. 이것이 기본 동작이지만, 이 섹션에서는 원격 호스트에 연결하는 방법을 다룰 것입니다. 이를 통해 Remote - SSH 확장을 사용하여 컨테이너 내에서 원격 호스트의 폴더를 열거나, 실행 중인 컨테이너에 연결하거나, 소켓을 사용하여 원격 개발 컨테이너를 구성, 생성 및 연결하는 방법으로 로컬 devcontainer.json 파일을 사용할 수 있습니다.

Remote - SSH 확장을 사용하여 연결

Linux 또는 macOS SSH 호스트를 사용하는 경우, Remote - SSH 및 Dev Containers 확장을 함께 사용할 수 있습니다. 로컬에 Docker 클라이언트를 설치할 필요조차 없습니다. 이를 위해서는

Remote - SSH 확장을 위한 설치 및 SSH 호스트 설정 단계를 따르십시오.
선택 사항: 비밀번호를 여러 번 입력할 필요가 없도록 서버에 대한 SSH 키 기반 인증을 설정하십시오.
SSH 호스트에 Docker를 설치하십시오. 로컬에 Docker를 설치할 필요는 없습니다.
Remote - SSH 확장을 위한 빠른 시작을 따라 호스트에 연결하고 해당 위치에 폴더를 여십시오.
명령 팔레트(F1, ⇧⌘P (Windows, Linux Ctrl+Shift+P))에서 **Dev Containers: Reopen in Container** 명령을 사용하십시오.

나머지 Dev Containers 빠른 시작은 그대로 적용됩니다. Remote - SSH 확장에 대한 자세한 내용은 해당 문서를 참조하십시오.

Remote - Tunnels 확장을 사용하여 연결

원격 호스트의 폴더를 컨테이너 안에서 열기 위해 Remote - Tunnels 및 Dev Containers 확장을 함께 사용할 수 있습니다. 로컬에 Docker 클라이언트를 설치할 필요조차 없습니다. 이는 위 SSH 호스트 시나리오와 유사하지만 Remote - Tunnels를 사용합니다. 이를 위해서는

Remote - Tunnels 확장을 위한 시작하기 지침을 따르십시오.
터널 호스트에 Docker를 설치하십시오. 로컬에 Docker를 설치할 필요는 없습니다.
Remote - Tunnels 확장을 위한 단계를 따라 터널 호스트에 연결하고 해당 위치에 폴더를 여십시오.
명령 팔레트(F1, ⇧⌘P (Windows, Linux Ctrl+Shift+P))에서 **Dev Containers: Reopen in Container** 명령을 사용하십시오.

나머지 Dev Containers 빠른 시작은 그대로 적용됩니다. Remote - Tunnels 확장에 대한 자세한 내용은 해당 문서를 참조하십시오.

Docker CLI를 사용하여 연결

이 모델은 로컬 Docker CLI가 연결할 수 있는 원격 호스트에서 Docker Engine이 실행 중이기만 하면 됩니다. Remote - SSH 및 Remote - Tunnels 확장을 사용하는 것이 더 쉽고 로컬에 Docker CLI를 설치할 필요조차 없지만, 이 모델은 명령줄에서 이미 연결 중인 호스트가 있는 상황에 유용할 수 있습니다. 이 접근 방식은 또한 이 원격 서버에서 이미 실행 중인 컨테이너에 연결하려는 경우에도 유용합니다.

기본 원격 예제

원격 Docker 호스트의 컨테이너에 연결하도록 VS Code를 설정하는 것은 Container Tools 확장의 containers.environment 속성을 settings.json에 설정하고 VS Code를 다시 시작하는(또는 창을 새로 고치는) 것만큼 간단할 수 있습니다.

예를 들어,

"containers.environment": {
    "DOCKER_HOST": "ssh://your-remote-user@your-remote-machine-fqdn-or-ip-here"
}

SSH를 사용하려면 지원되는 SSH 클라이언트가 필요하며, 원격 호스트에 대해 키 기반 인증이 구성되어 있고, 키가 로컬 SSH 에이전트에 가져와져야 합니다. 에이전트 구성 및 키 추가에 대한 자세한 내용은 SSH 키를 Git와 함께 사용 문서를 참조하십시오.

이 시점에서 원격 호스트의 컨테이너에 연결할 수 있습니다. 이 섹션의 뒷부분에서 설정 및 환경 변수 또는 Docker 컨텍스트를 사용하여 연결하는 방법에 대한 추가 정보를 다룰 것입니다.

devcontainer.json의 경우 한 가지 추가 단계가 있습니다. 로컬 파일 시스템을 가리키지 않도록 구성된(또는 자동 구성된) 모든 바인드 마운트를 업데이트해야 합니다.

이 설정에는 두 가지 변형이 있습니다. 첫 번째는 원격 개발 컨테이너를 먼저 생성한 다음 명명된 볼륨에 소스 코드를 복제하는 것입니다. 이는 원격 호스트의 파일 시스템에 직접 액세스할 필요가 없기 때문입니다.

이 설정에 대한 기본적인 devcontainer.json 예는 다음과 같습니다.

{
  "image": "node", // Or "dockerFile"
  "workspaceFolder": "/workspace",
  "workspaceMount": "source=remote-workspace,target=/workspace,type=volume"
}

실제로 명령 팔레트(F1)의 Dev Containers: Clone Repository in Container Volume... 명령은 이와 동일한 기술을 사용합니다. GitHub 리포지토리에 이미지 또는 Dockerfile을 참조하는 devcontainer.json 파일이 이미 있는 경우, 이 명령은 바인드 마운트 대신 명명된 볼륨을 자동으로 사용합니다. 이 역시 원격 호스트에서 작동합니다.

두 번째 접근 방식은 원격 머신의 폴더를 컨테이너로 바인드 마운트하는 것입니다. 이를 위해서는 원격 파일 시스템에 액세스할 수 있어야 하지만, 원격 머신의 기존 소스 코드를 사용할 수도 있습니다.

위 예제의 workspaceMount 속성을 이 모델을 대신 사용하도록 업데이트하십시오.

"workspaceMount": "source=/absolute/path/on/remote/machine,target=/workspace,type=bind,consistency=cached"

어느 경우든, 테스트하려면 명령 팔레트(F1)에서 Dev Containers: Open Folder in Container...를 실행하고 .devcontainer.json 파일이 있는 로컬 폴더를 선택하십시오.

기존 또는 사전 정의된 devcontainer.json 변환에서 Docker Compose와 같은 다른 시나리오에 대한 정보를 참조하십시오.

VS Code 설정 또는 로컬 환경 변수를 사용하여 연결

이미 실행 중인 원격 Docker 호스트가 있는 경우, 작업 공간 또는 사용자 settings.json에서 다음 속성을 사용하여 호스트를 지정할 수 있습니다.

SSH 프로토콜

최신 버전의 Docker(18.06+)는 원격 Docker 호스트에 연결하기 위한 SSH 프로토콜 지원을 추가했습니다. 이것은 settings.json에 한 가지 속성만 설정하면 되므로 구성하기 쉽습니다.

지원되는 SSH 클라이언트를 설치하고, 키 기반 인증을 구성한 다음, 키를 로컬 SSH 에이전트에 가져오십시오(Windows 및 Linux에서는 기본적으로 실행되지 않는 경우가 많습니다). 에이전트 구성 및 키 추가에 대한 자세한 내용은 SSH 키를 Git와 함께 사용 문서를 참조하십시오.

그런 다음, 다음 Container Tools 확장 containers.environment 속성을 settings.json에 추가하십시오 (값을 적절히 바꾸십시오).

"containers.environment": {
    "DOCKER_HOST": "ssh://your-remote-user@your-remote-machine-fqdn-or-ip-here"
}

VS Code를 다시 시작하거나(또는 창을 새로 고침)하면 이제 원격 호스트에서 실행 중인 모든 컨테이너에 연결할 수 있습니다. 또한 특수한 로컬 devcontainer.json 파일을 사용하여 원격 개발 컨테이너를 생성/연결할 수도 있습니다.

팁: 이것이 작동하지 않지만 명령줄에서 SSH를 사용하여 호스트에 연결할 수 있다면, SSH 에이전트가 인증 키와 함께 실행 중인지 확인하십시오. 모든 것이 실패하면, 대신 SSH 터널을 대체 방법으로 사용할 수 있습니다.

TCP 프로토콜 사용

SSH 프로토콜은 자체 인증 메커니즘을 내장하고 있지만, TCP 프로토콜을 사용하는 경우 종종 settings.json에서 다른 Container Tools 확장 속성을 설정해야 합니다. 다음과 같습니다.

"containers.environment": {
    "DOCKER_HOST": "tcp://your-remote-machine-fqdn-or-ip-here:port",
    "DOCKER_CERT_PATH": "/optional/path/to/folder/with/certificate/files",
    "DOCKER_TLS_VERIFY": "1" // or "0"
}

SSH와 마찬가지로, 설정을 적용하려면 VS Code를 다시 시작하거나(또는 창을 새로 고침)하십시오.

settings.json 대신 환경 변수 사용

settings.json을 사용하고 싶지 않다면, 대신 터미널에서 환경 변수를 설정할 수 있습니다. 이를 위한 단계는 다음과 같습니다.

VS Code의 모든 인스턴스를 종료하십시오.
VS Code가 운영 체제의 PATH에 있는지 확인하십시오.
터미널/명령 프롬프트에서 환경 변수(예: DOCKER_HOST)를 설정하십시오.
이와 동일한 터미널/명령 프롬프트에서 code를 입력하여 변수가 설정된 상태로 VS Code를 시작하십시오.

Docker 컨텍스트를 사용하여 연결

Docker 컨텍스트를 사용하면 다른 호스트와 상호 작용할 수 있습니다. 각 호스트에 대한 컨텍스트를 설정하고 전환할 수 있습니다.

docker context create를 사용하여 새 컨텍스트를 생성합니다. 현재 컨텍스트는 docker context use <context>를 사용하여 변경할 수 있습니다.

Container Tools 확장은 containers.environment 설정을 제공하며, 여기서 DOCKER_HOST 또는 DOCKER_CONTEXT와 같은 환경 변수를 설정할 수 있으며, 이는 Dev Containers 확장에서도 인식됩니다.

참고: 위의 설정은 Container Tools 확장이 설치된 경우에만 표시됩니다. Container Tools 확장이 없으면 Dev Containers는 현재 컨텍스트를 사용합니다.

기존 또는 사전 정의된 devcontainer.json 변환

기존 또는 사전 정의된 로컬 devcontainer.json을 원격으로 변환하려면 다음 단계를 따르십시오.

파일을 변환하려는 로컬 폴더를 VS Code에서 열어보십시오 (원격 폴더는 안 됩니다).
devcontainer.json이 있는 폴더를 선택하지 않은 경우, 명령 팔레트(F1)에서 Dev Containers: Add Container Configuration File...을 실행하여 사전 정의된 파일을 선택할 수 있습니다.
소스 코드 마운트를 수정하기 위해 .devcontainer/devcontainer.json 또는 .devcontainer.json이 참조하는 내용에 따라 다음 단계를 따르십시오.

Dockerfile 또는 이미지:

원격 호스트에 로그인 액세스 권한이 없는 경우, 소스 코드에 Docker "볼륨"을 사용하십시오. .devcontainer/devcontainer.json을 다음과 같이 업데이트하십시오 (원하는 경우 remote-workspace를 고유한 볼륨 이름으로 바꾸십시오).
```
"workspaceMount": "source=remote-workspace,target=/workspace,type=volume"
"workspaceFolder": "/workspace",
```
로그인 액세스 권한이 있는 경우, 대신 원격 파일 시스템 바인드 마운트를 사용할 수 있습니다.
```
"workspaceMount": "source=/absolute/path/on/remote/machine,target=/workspace,type=bind,consistency=cached"
"workspaceFolder": "/workspace",
```
workspaceMount 속성은 다른 시나리오를 염두에 두고 있다면 Docker CLI --mount 플래그와 동일한 값을 지원합니다.

Docker Compose:

원격 호스트에 로그인 액세스 권한이 없는 경우, docker-compose.yml을 업데이트하거나(확장) 하십시오. your-service-name-here를 devcontainer.json의 "service" 속성에 지정된 값으로 바꾸고 remote-workspace를 고유한 볼륨 이름으로 바꾸십시오.
```
version: '3'
services:
  your-service-name-here:
    volumes:
        - remote-workspace:/workspace
    # ...

volumes:
  remote-workspace:
```
로그인 액세스 권한이 있는 경우, 대신 원격 파일 시스템 바인드 마운트를 사용할 수 있습니다.
```
version: '3'
services:
  your-service-name-here:
    volumes:
      - /absolute/path/on/remote/machine:/workspace:cached
    # ...
```
다른 시나리오를 지원해야 하는 경우 volumes에 대한 Docker Compose 문서를 참조하십시오.
명령 팔레트(F1)에서 Dev Containers: Reopen in Container 명령을 실행하거나 Dev Containers: Rebuild Container를 실행하십시오.
볼륨을 바인드 마운트 대신 사용한 경우, 컨테이너 내에서 터미널을 열려면 (⌃⇧` (Windows, Linux Ctrl+Shift+`))을 사용하십시오. 여기서 git clone을 실행하여 소스 코드를 다운로드하고, 파일 > 열기... / 폴더 열기...를 사용하여 복제된 리포지토리를 여십시오.

다음 번에 동일한 컨테이너에 연결하려면, VS Code 창에서 Dev Containers: Open Folder in Container...를 실행하고 동일한 로컬 폴더를 선택하십시오.

선택 사항: 원격 소스 코드를 로컬에서 사용할 수 있도록 만들기

소스 코드를 Docker 볼륨이 아닌 원격 호스트의 파일 시스템에 저장하는 경우, 파일을 로컬에서 액세스할 수 있는 몇 가지 방법이 있습니다.

SSHFS를 사용하여 원격 파일 시스템 마운트.
rsync를 사용하여 원격 호스트에서 로컬 머신으로 파일 동기화.
mount 명령을 사용하는 경우 (Docker Machine 사용 시) mount 명령을 사용하십시오.

SSHFS 또는 Docker Machine의 mount 명령은 파일 동기화가 필요 없는 더 편리한 옵션입니다. 그러나 VS Code를 통해 작업하는 것보다 성능이 훨씬 느리므로, 단일 파일 편집 및 콘텐츠 업로드/다운로드에 가장 적합합니다. 많은 파일을 한 번에 대량으로 읽고 쓰는 애플리케이션(예: 로컬 소스 제어 도구)을 사용해야 하는 경우 rsync가 더 나은 선택입니다.

12/10/2025