jay817/wiki

Fork 0

Files

History

jay817 eae6fc2d21 Update wsl-docker/README.md

2025-08-31 09:42:29 +09:00

README.md

Update wsl-docker/README.md

2025-08-31 09:42:29 +09:00

README.md

본 문서에서는 Fresh Windows 10 (or 11)에 WSL2 > Debian > Docker > NVIDIA CUDA를 설치하는 법을 순서대로 설명한다.

WSL2 설치

Ref: https://learn.microsoft.com/ko-kr/windows/wsl/install

1. 새로운 Windows에 WSL을 설치하는 경우

Powershell (관리자로 실행):
```
wsl --install
```
설치를 마친 후 Windows 재부팅을 해야 다음 단계로 넘어갈 수 있다.

2. WSL 리눅스 배포판 설치

Powershell (관리자로 실행):
```
wsl --install -d Debian
```
다른 배포판을 설치할 수도 있지만 Debian이 제일 근본이다.

3. Windows Terminal 설치

https://apps.microsoft.com/detail/9n0dx20hk701?hl=en-US&gl=US

현대적인 디자인으로 CMD, powershell, Debian Bash 각각 탭으로 켤수 있다.

Docker 설치

4. WSL에 docker 설치

docker daemon을 실행하려면 systemd가 켜져있어야 한다.
정상적인 linux는 이미 systemd가 실행되어 있지만 wsl에서는 기본적으로 꺼져있다.

Debian Bash

sudo tee -a /etc/wsl.conf <<'EOF'
[boot]
systemd=true
EOF

Powershell (관리자로 실행):

wsl --shutdown # 종료
wsl # 재시작

Debian Bash:

sudo apt-get update && sudo apt-get install -y curl gpg
curl -fsSL https://get.docker.com | sudo sh
sudo adduser $USER docker # sudo 없이 docker 실행
su $USER # group 변경은 로그인해야 적용되므로 자신에게 다시 로그인
docker run hello-world

성공 메시지:
```
Hello from Docker!
```

5. WSL background 실행

WSL는 기본적으로 실행중인 터미널이 하나도 없으면 WSL 자체가 종료되도록 되어 있어서 서버를 굴릴수가 없다.

Windows에 python은 설치되어 있어야 한다.
Win+R > shell:startup : 시작프로그램 폴더가 열린다.

메모장으로 아래의 wsl.pyw 파일을 생성하여 시작프로그램 폴더에 저장

while True: (S := __import__('subprocess')).run(['wsl'], creationflags=S.CREATE_NO_WINDOW)

이 wsl.pyw 파일을 더블클릭해서 실행해보아도 눈에 보이는 것은 없지만, 백그라운드 터미널 하나가 실행되어, wsl이 꺼지지 않게 된다.
컴퓨터를 재시작 할 경우에도 항상 하나가 켜져 있을 것이다.
주의 wsl --shutdown으로 강제종료하여도 계속 wsl을 시작할 것이기 때문에 완전한 종료를 원할 경우에는, 저 파일을 지우고 재부팅하는 것이 제일 간단할 것이다.

Docker에 NVIDIA 설치

WSL에서 nvidia-driver까지는 기본으로 깔아주므로 별다른 설정 없이 Debian에서 nvidia-smi를 사용할 수 있지만,
docker container 내부에서도 CUDA를 사용하기 위해서는 nvidia-container-toolkit를 추가로 설치해야 한다.

(추가) CUDA 12.6 설치

WSL에서 설치하는 CUDA는 12.4인데 CUDA 12.9을 필요로 하는 경우 아래와 같이 설치한다.

https://developer.nvidia.com/cuda-downloads?target_os=Linux&target_arch=x86_64&Distribution=Debian&target_version=12&target_type=deb_local

wget https://developer.download.nvidia.com/compute/cuda/repos/debian12/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt-get update
sudo apt-get -y install cuda-toolkit-12-9

nvidia-smi

6. nvidia-container-toolkit 설치

https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html#installing-with-apt

위의 명령어를 따라가면 되는데 결과적으로 WSL Debian 기준 아래와 같이 실행하면 된다.

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
  && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
    sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

docker run --gpus all debian nvidia-smi # test

nvidia-smi가 잘 실행되면 성공이다.

[추가] WSL에 Python & Jupyter Lab 설치

7. debian에 python 설치

sudo apt-get update && sudo apt-get install -y python3-venv
cd ~
python3 -m venv .venv # ~/.venv에 가상환경 python을 만든다.
echo 'export PATH="$HOME/.venv/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
which python
# /home/<your-id>/.venv/bin/python
which pip
# /home/<your-id>/.venv/bin/pip

이제 activate/deactivate 신경쓰지 않고 pip install로 설치하는 것들은 ~/.venv 안에 잘 설치된다.

pip install jupyterlab ipywidgets

jupyter lab --IdentityProvider.token="" # 암호 없이 localhost:8888 로그인 가능

8. Windows 재부팅시 Jupyter Lab 자동시작

먼저 ssh를 통해 비밀번호 없이 자신에게 접속할수 있도록 세팅해야 한다.

chmod 0755 $HOME
sudo apt-get update && sudo apt-get install -y openssh-server
sudo systemctl start ssh # ssh-server 시작
ssh-keygen # [Enter] 계속 눌러 ~/.ssh 폴더에 비밀키 생성

ssh localhost # 자기자신으로 접속된다.

ssh-copy-id localhost # 자기자신에게 공개키를 복사한다.
ssh localhost # 자기자신으로 접속되는데 비밀번호가 필요하지 않게 된다.

mkdir -p ~/.jupyter # 없으면 폴더를 만든다.
cd ~/.jupyter

tee Dockerfile << 'EOF'
FROM alpine:latest
RUN apk add --no-cache openssh-client
EOF

tee docker-compose.yml << 'EOF'
services:
  jupyter:
    build: .
    container_name: jupyter
    restart: unless-stopped
    stop_grace_period: 0s
    network_mode: host
    volumes:
      - $HOME/.ssh:/root/.ssh
    entrypoint: ssh -tt $USER@localhost '~/.venv/bin/jupyter-lab --IdentityProvider.token=""'
EOF

docker compose up -d # Jupyter 서버 시작 (이미 켜져있으면 8889에 하나 더 켜진다.)

FROM alpine:latest: 가벼운 Alpine Linux 이미지를 사용합니다.
container_name: jupyter: 컨테이너 이름을 'jupyter'로 지정합니다.
restart: unless-stopped: 컨테이너가 중지되지 않는 한 항상 재시작합니다.
stop_grace_period: 0s: 컨테이너 중지 시 즉시 종료합니다.
network_mode: host: 호스트의 네트워크를 직접 사용합니다.
volumes: - $HOME/.ssh:/root/.ssh: SSH 키를 컨테이너와 공유합니다.
entrypoint: sh -c: 쉘 명령을 실행할 수 있게 합니다.
command::
- apk add openssh-client: SSH 클라이언트를 설치합니다.
- ssh -tt $USER@localhost '~/.venv/bin/jupyter lab --IdentityProvider.token=""': SSH를 통해 Jupyter Lab을 실행합니다.

이 설정은 다음과 같은 이점이 있습니다:

Alpine 이미지를 사용하여 가볍습니다.
SSH 키를 호스트와 공유하여 인증 문제를 해결합니다.
호스트 네트워크를 사용하여 localhost 접근이 가능합니다.
컨테이너가 자동으로 재시작되어 안정성을 높입니다.

docker compose logs # 서버 상태 보기
cd ~/.jupyter && docker compose down # 서버 종료

만약 5. WSL background 실행과 8. Windows 재부팅시 Jupyter Lab 자동시작 모두 정확히 설정되었다면 윈도우를 재부팅하고 바로 localhost:8888에 접속할 수 있게 된다.