로컬 AI 모델 구동하기-2

2단계: Docker 기초

목표

• Docker 핵심 개념 이해 (Image / Container / Volume)
• 기본 명령어 실전 경험
• docker run 옵션의 의미를 이해하며 사용

---

2-1. Docker 설치

GPU 컨테이너까지 사용할 예정이면 sudo snap install docker 대신 Docker 공식 apt 저장소로 설치합니다.
Snap Docker는 docker 그룹이 없거나 NVIDIA Container Toolkit 연동에서 예상과 다르게 동작할 수 있습니다.

설치 전: apt update 오류가 있으면 먼저 해결

apt update가 아래처럼 실패하면 Docker 설치도 중간에 멈춥니다.

E: The repository 'https://ppa.launchpadcontent.net/thopiekar/openrgb/ubuntu noble Release' does not have a Release file.

이 경우 문제 PPA를 비활성화합니다.

sudo add-apt-repository --remove ppa:thopiekar/openrgb
sudo apt update

add-apt-repository 명령이 없거나 제거되지 않으면 해당 source 파일을 직접 찾아 비활성화합니다.

grep -R "thopiekar/openrgb" /etc/apt/sources.list /etc/apt/sources.list.d/
sudo rm /etc/apt/sources.list.d/*openrgb*
sudo apt update

apt update 출력에 더 이상 thopiekar/openrgb 오류가 없어야 다음 단계로 진행합니다.

이미 Snap Docker를 설치했다면 제거하고 apt 방식으로 다시 설치합니다.

sudo snap remove docker

Docker 공식 apt 저장소로 설치

이미 /etc/apt/sources.list.d/docker.sources를 잘못 만들었다면 같은 명령으로 덮어쓰면 됩니다.

Suites에는 amd64가 아니라 noble, jammy 같은 Ubuntu 코드네임이 들어갑니다.

# 1. 필수 패키지 설치
sudo apt update
sudo apt install -y ca-certificates curl

# 2. Docker GPG 키 추가
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# 3. Docker apt 저장소 추가
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

# 4. Docker Engine 설치
sudo apt update
apt-cache policy docker-ce docker-ce-cli containerd.io
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 5. 현재 유저에게 권한 부여 (sudo 없이 사용하기 위해)
sudo usermod -aG docker $USER

# 재로그인 후 적용됨 — 현재 세션에 즉시 적용하려면:
newgrp docker

# 6. 설치 확인
docker --version
docker info
docker run hello-world

복사할 때 curl -fsSL [https://...](https://...) 형태가 되면 안 됩니다.
터미널에는 반드시 curl -fsSL https://download.docker.com/linux/ubuntu/gpg ... 처럼 순수 URL만 붙여 넣습니다.

docker-ce 설치 후보가 없다고 나오면

아래처럼 나오면 Docker 저장소가 패키지 후보로 잡히지 않은 상태입니다.

Package docker-ce is not available
E: Package 'docker-ce' has no installation candidate
E: Unable to locate package containerd.io

sudo apt update 출력에 download.docker.com이 보이지 않으면 Docker 저장소가 등록되지 않은 것입니다. 위의 "Docker apt 저장소 추가" 블록을 다시 실행합니다.

먼저 현재 배포판 정보와 Docker 저장소 설정을 확인합니다.

. /etc/os-release
echo "ID=$ID VERSION_CODENAME=$VERSION_CODENAME UBUNTU_CODENAME=${UBUNTU_CODENAME:-}"
cat /etc/apt/sources.list.d/docker.sources
apt-cache policy docker-ce

VERSION_CODENAME이 Ubuntu 코드네임(noble, jammy 등)이 아니라 Linux Mint 같은 파생 배포판 코드네임이면 Suites를 Ubuntu 기반 코드네임으로 직접 지정합니다.

예: Ubuntu 24.04 기반이면 noble

sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: noble
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update
apt-cache policy docker-ce
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

예: Ubuntu 22.04 기반이면 jammy로 바꿉니다.

---

2-2. 핵심 개념

Image (이미지)

• 비유: 설치 CD, 또는 프로그램 설계도
• 변경 불가 (읽기 전용)
• Docker Hub에서 다운로드하거나 직접 빌드

Container (컨테이너)

• 비유: Image를 실행한 인스턴스 (프로그램 실행 상태)
• 같은 Image로 여러 Container 생성 가능
• 컨테이너를 삭제하면 내부 데이터도 사라짐

Volume (볼륨)

• 비유: 컨테이너 밖에 있는 외장 드라이브
• 컨테이너를 삭제해도 데이터 보존
• -v /host경로:/컨테이너경로 형태로 마운트

---

2-3. 첫 번째 컨테이너 실행

# hello-world 이미지 실행
docker run hello-world

내부적으로 일어나는 일:

1. 로컬에 hello-world 이미지가 없음
2. Docker Hub에서 자동 다운로드 (pull)
3. 이미지로 컨테이너 생성 후 실행
4. 출력 후 컨테이너 종료

---

2-4. 자주 쓰는 명령어

이미지 관리

docker images                    # 로컬 이미지 목록
docker pull ubuntu:22.04         # 이미지 다운로드
docker rmi ubuntu:22.04          # 이미지 삭제
docker image prune               # 사용 안 하는 이미지 정리

컨테이너 실행

# 기본 실행 (실행 후 바로 종료)
docker run ubuntu:22.04 echo "hello"

# 백그라운드 실행 (-d: detach)
docker run -d --name mycontainer ubuntu:22.04 sleep 3600

# 인터랙티브 모드 (-it: interactive + tty)
docker run -it ubuntu:22.04 bash

# 포트 연결 (-p 호스트포트:컨테이너포트)
docker run -d -p 8080:80 nginx

# 볼륨 마운트 (-v)
docker run -v /home/user/data:/data ubuntu:22.04 ls /data

# 자동 삭제 (종료 시 컨테이너 자동 제거)
docker run --rm ubuntu:22.04 echo "일회용"

컨테이너 관리

docker ps                        # 실행 중인 컨테이너
docker ps -a                     # 전체 컨테이너 (종료 포함)
docker stop mycontainer          # 정상 종료
docker start mycontainer         # 재시작
docker rm mycontainer            # 컨테이너 삭제
docker container prune           # 종료된 컨테이너 모두 삭제

컨테이너 내부 접근

# 실행 중인 컨테이너에 명령 실행
docker exec -it mycontainer bash

# 로그 확인
docker logs mycontainer
docker logs -f mycontainer       # 실시간 (follow)

---

2-5. docker run 주요 옵션 정리

옵션	의미	예시
-d	백그라운드 실행	-d
-it	터미널 연결 (인터랙티브)	-it
--name	컨테이너 이름 지정	--name vllm-server
-p	포트 연결	-p 8000:8000
-v	볼륨/폴더 마운트	-v ~/models:/models
--rm	종료 시 자동 삭제	--rm
--restart	재시작 정책	--restart always
-e	환경변수 설정	-e CUDA_VISIBLE_DEVICES=0
--gpus	GPU 할당	--gpus all

---

2-6. 실습: nginx 웹서버 띄워보기

# nginx 실행 (포트 8080으로 접근 가능하게)
docker run -d --name web -p 8080:80 nginx

# 브라우저에서 http://localhost:8080 접속
# 또는 터미널에서:
curl http://localhost:8080

# 로그 확인
docker logs web

# 정리
docker stop web && docker rm web

---

체크리스트

• docker run hello-world 성공
• docker ps, docker images 명령어 이해
• nginx 실습 완료 (브라우저/curl로 확인)
• -d, -p, -v, --name 옵션 의미 설명할 수 있음