Docker Desktop 없이 WSL2 + npiperelay + socat으로 Docker CLI 구성하기

이 글은 Windows에서 Docker Desktop 없이, WSL2 내부에 설치된 Docker Engine을 Windows PowerShell에서 직접 제어할 수 있도록 설정한 과정을 순차적으로 정리한 것이다. 주요 구성 요소는 다음과 같다.

• WSL2 (예: Ubuntu)에 설치된 Docker Engine
• Windows에서 Docker CLI (docker.exe) 사용
• npiperelay를 이용해 Windows PowerShell에서 localhost로 요청 전달
• socat을 이용해 WSL 내부의 /var/run/docker.sock을 TCP로 노출

1. WSL2 환경에 Docker Engine 설치

sudo apt update
sudo apt install -y docker.io socat
sudo usermod -aG docker $USER

필요 시 systemd를 통해 자동 실행 설정 가능하다. 이때, /etc/wsl.conf에 다음 설정이 필요하다.

[boot]
systemd=true

설정 후에는 다음 명령어로 WSL을 완전히 종료하고 다시 시작해야 적용된다.

wsl --shutdown

또한 docker.io를 설치하면 dockerd에 대한 systemd 서비스 유닛이 함께 설치되므로 별도로 서비스 파일을 작성할 필요는 없다. 다음 명령으로 활성화만 하면 된다.

sudo systemctl enable docker
sudo systemctl start docker

2. socat으로 Docker socket 중계

socat은 다양한 소켓, 포트, 파일 등을 상호 연결할 수 있는 범용 소켓 중계 도구이다. 여기에서는 WSL2 내부의 Docker UNIX 도메인 소켓(/var/run/docker.sock)을 Windows 측에서 접근할 수 있도록 TCP 포트(2375)로 노출하는 데 사용한다.

사용할 명령 형식은 다음과 같다.

socat TCP-LISTEN:2375,reuseaddr,fork UNIX-CONNECT:/var/run/docker.sock

• TCP-LISTEN:2375: WSL 내부의 2375 포트를 열어 외부 요청 수신
• reuseaddr: 포트를 재사용 가능하게 함
• fork: 연결 요청마다 새 프로세스를 생성하여 병렬 처리
• UNIX-CONNECT:/var/run/docker.sock: Docker UNIX 소켓으로 연결

이 명령은 한 번 실행해도 되지만, 자동 실행을 위해 systemd 서비스를 사용하는 것이 더 효율적이고 안정적이다.

WSL2 환경에서 Docker Engine이 실행 중일 때, 다음과 같은 방법으로 socat을 systemd 서비스로 등록하여 Docker 소켓을 TCP로 노출할 수 있다.

systemd로 socat 자동 실행 설정

Ubuntu 22.04 이상에서 systemd가 활성화된 상태라면 다음과 같이 설정할 수 있다.

1. 서비스 파일 생성:

sudo nano /etc/systemd/system/socat-docker-relay.service

내용:

[Unit]
Description=Socat Docker relay
After=network.target docker.service

[Service]
ExecStart=/usr/bin/socat TCP-LISTEN:2375,reuseaddr,fork UNIX-CONNECT:/var/run/docker.sock
Restart=always

[Install]
WantedBy=default.target

1. 서비스 등록 및 활성화:

참고: systemctl daemon-reexec는 systemd 프로세스를 다시 실행하여 변경 사항(예: systemd 자체 설정 변경)을 반영하는 명령이며, systemctl daemon-reload는 새로운 서비스 유닛 파일을 systemd가 인식하도록 하기 위해 필요하다. 서비스 유닛 파일을 새로 만들거나 수정한 후에는 이 두 명령을 통해 systemd가 변경된 구성을 적용하도록 해야 한다.

sudo systemctl daemon-reexec
sudo systemctl daemon-reload
sudo systemctl enable socat-docker-relay.service
sudo systemctl start socat-docker-relay.service

이제 WSL 부팅 시 자동으로 socat이 실행되어 Docker 소켓이 TCP로 노출된다.

3. Windows에 Docker CLI 설치

Windows 측에서 Docker CLI를 사용하는 이유는 PowerShell 또는 기타 도구에서 직접 docker 명령어를 실행해 WSL2 내부의 Docker Engine을 제어하기 위한 것이다. 이는 Docker Desktop을 설치하지 않고도 로컬 개발 환경에서 컨테이너를 관리할 수 있도록 하며, 특히 Windows에서 개발 도구나 자동화 스크립트 등을 활용하려는 경우 필수적이다.

1. https://download.docker.com/win/static/stable/x86_64/ 에서 최신 docker-XX.XX.X.zip 다운로드
2. 압축 해제 후 docker.exe를 예: C:\Tools\Docker\에 복사
3. 환경 변수 PATH에 해당 경로 추가

docker version

정상 출력되면 CLI가 설치된 것으로 볼 수 있다.

4. Windows에 npiperelay 설치

1. https://github.com/jstarks/npiperelay/releases 에서 최신 npiperelay.exe 다운로드
2. 예: C:\Tools\npiperelay\ 에 저장

start-wsl-docker.ps1 스크립트:

$npiperelayPath = "C:\Tools\npiperelay\npiperelay.exe"
Start-Process -FilePath $npiperelayPath `
  -ArgumentList '-ep -s //./pipe/docker_engine -t tcp:localhost:2375' `
  -WindowStyle Hidden

이 스크립트를 실행하면 Windows의 Named Pipe 요청이 TCP 2375로 중계된다.

Windows 작업 스케줄러에 등록하는 방법

npiperelay 자동 실행 등록

1. 작업 스케줄러(Task Scheduler) 실행 (Windows 검색에서 “작업 스케줄러”)
2. 오른쪽에서 작업 만들기(Create Task) 클릭
3. 일반 탭:

• 이름: Start WSL Docker Proxy
• [✓] 가장 높은 수준의 권한으로 실행

4. 트리거 탭:

• 새로 만들기 → 트리거: 로그온 시 또는 시스템 시작 시 선택

5. 동작 탭:

• 새로 만들기 → 동작: 프로그램 시작
• 프로그램/스크립트: powershell.exe
• 인수 추가:-ExecutionPolicy Bypass -File "C:\Tools\npiperelay\start-wsl-docker.ps1"

이 설정을 통해 Windows가 부팅되면 자동으로 npiperelay가 실행되어 PowerShell에서도 곧바로 Docker CLI를 사용할 수 있다.

5. PowerShell에서 Docker 명령 실행

PowerShell에서 환경 변수 설정 후, Docker 명령어 사용

$env:DOCKER_HOST = "tcp://localhost:2375"
docker info
docker run hello-world

위와 같이 DOCKER_HOST 환경 변수는 PowerShell 세션이 새로 열릴 때마다 다시 설정해줘야 한다. 이를 매번 입력하는 것이 번거롭다면 PowerShell 프로필($PROFILE)에 해당 줄을 추가하여 자동으로 설정되도록 할 수 있다.

notepad $PROFILE

파일에 다음 줄 추가:

$env:DOCKER_HOST = "tcp://localhost:2375"

이제 PowerShell을 열 때마다 자동으로 환경 변수가 설정되어 Docker 명령을 바로 사용할 수 있다.

Docker Desktop 없이도 WSL2 내부 Docker Engine이 정상 동작하는 것을 확인할 수 있을 것이다.