Docker와 컨테이너

기본 개념

컨테이너는 가상머신(VM)과 다르다. VM은 하드웨어를 흉내 내고 그 위에 별도의 OS kernel을 띄운다. 컨테이너는 호스트의 kernel을 공유하면서, 파일시스템·프로세스·네트워크를 격리한 프로세스다. 그래서 가볍고 빨리 뜨지만, kernel과 kernel 모듈(GPU 드라이버 포함)은 호스트의 것을 쓴다. 이 사실이 뒤의 GPU 절의 출발점이다.

Docker의 다섯 가지 개념은 다음과 같다.

image 하나로 컨테이너를 여러 개 띄울 수 있다. 컨테이너 안에서 파일을 고치면 그 컨테이너의 쓰기 layer에만 기록되고, image와 다른 컨테이너는 그대로다. 컨테이너를 지우면 쓰기 layer도 사라진다. 이 성질이 "실험이 환경을 더럽히지 않는다"는 장점이자, "결과를 컨테이너 안에 저장하면 사라진다"는 함정이다.

tag와 digest의 차이는 재현에서 결정적이다. tag는 registry에서 언제든 다른 image로 옮길 수 있는 이름이고, digest는 내용 자체에서 계산된다. 이 관계를 해시로 흉내 낸다(실제 image digest는 image의 manifest 파일 내용의 SHA-256이다).

import hashlib

def digest(content: bytes) -> str:
    return "sha256:" + hashlib.sha256(content).hexdigest()[:12] + "..."

v1 = b'{"layers": ["ubuntu-base", "python-3.12", "numpy-2.5.4"]}'
v2 = b'{"layers": ["ubuntu-base", "python-3.12", "numpy-2.5.5"]}'   # 한 글자 차이

registry = {"lab/proj:latest": digest(v1)}
print("1월 push  lab/proj:latest ->", registry["lab/proj:latest"])
registry["lab/proj:latest"] = digest(v2)                             # 같은 tag로 다시 push
print("6월 push  lab/proj:latest ->", registry["lab/proj:latest"])
print("1월 내용을 digest로 다시 계산 ->", digest(v1))

1월 push  lab/proj:latest -> sha256:4a2eddfbe00e...
6월 push  lab/proj:latest -> sha256:c20fdab807d9...
1월 내용을 digest로 다시 계산 -> sha256:4a2eddfbe00e...

같은 이름 lab/proj:latest가 6월에는 다른 내용을 가리킨다. 반면 1월 내용의 digest는 언제 계산해도 같다. 그래서 실험 기록에는 tag가 아니라 lab/proj@sha256:... 형식의 digest를 남긴다. 로컬 image의 digest는 docker image inspect --format '{{json .RepoDigests}}' lab/proj:latest로 확인한다(registry에 push했거나 registry에서 pull한 image에만 있다).

Dockerfile

Dockerfile은 image를 만드는 절차를 적은 파일이다. 각 줄(instruction)이 실행되어 layer 하나를 만든다. 연구용 Python 프로젝트의 Dockerfile은 대체로 다음 구조를 따른다(집필 시점 예시. 이 책의 실습 파일 labs/environments/docker/Dockerfile과 같은 구조다).

# syntax=docker/dockerfile:1
FROM python:3.12-slim

# uv 실행 파일만 공식 이미지에서 복사한다
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

WORKDIR /app
ENV UV_LINK_MODE=copy UV_COMPILE_BYTECODE=1

# 1) 의존성 기록만 먼저 복사해 설치한다
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked --no-dev --no-install-project

# 2) 코드는 마지막에 복사한다
COPY . .
RUN uv sync --locked --no-dev

ENV PATH="/app/.venv/bin:$PATH"
CMD ["python", "train.py"]

base image 선택. FROM이 정하는 base image가 OS·glibc·시스템 라이브러리를 정한다. GPU를 쓰는 연구용 image의 base는 두 계열로 나뉜다.

• 일반 OS·Python image(예: python:3.12-slim, ubuntu:24.04): PyTorch를 pip·uv wheel로 설치하면 CUDA runtime이 wheel과 함께 들어오므로(3.1장, 3.4장), base에 CUDA가 없어도 GPU 학습이 된다. image가 작고 단순하다.
• CUDA image 계열(NVIDIA가 배포하는 nvidia/cuda image 등): CUDA 라이브러리가 미리 들어 있다. 보통 base(최소), runtime(실행 라이브러리), devel(컴파일러 nvcc와 헤더 포함) 같은 변형과 cuDNN 포함 여부, Ubuntu 버전이 tag에 표시된다. custom CUDA extension을 빌드해야 하면 devel 변형이 필요하다. 어떤 tag가 있는지는 registry 페이지에서 확인한다.

layer와 build cache. Docker는 각 줄의 결과를 cache하고, 다음 빌드에서 그 줄의 입력(명령 문자열, 복사하는 파일의 내용)이 같으면 다시 실행하지 않는다. 어떤 줄의 입력이 바뀌면 그 줄과 그 뒤의 모든 줄을 다시 실행한다. 그래서 줄의 순서가 빌드 시간을 결정한다. 자주 바뀌는 것(코드)을 뒤에, 드물게 바뀌는 것(의존성 기록)을 앞에 둔다. 두 순서를 비교한다.

def rebuilt(dockerfile, changed):
    """changed 파일이 바뀌었을 때 다시 실행되는 줄. 한 줄이 무효화되면 그 뒤는 모두 다시 실행된다."""
    for i, (line, inputs) in enumerate(dockerfile):
        if inputs & changed:
            return [l for l, _ in dockerfile[i:]]
    return []

code_first = [("FROM python:3.12-slim", set()),
              ("COPY . /app", {"pyproject.toml", "uv.lock", "train.py"}),
              ("RUN uv sync --locked", set())]
lock_first = [("FROM python:3.12-slim", set()),
              ("COPY pyproject.toml uv.lock /app/", {"pyproject.toml", "uv.lock"}),
              ("RUN uv sync --locked --no-install-project", set()),
              ("COPY . /app", {"pyproject.toml", "uv.lock", "train.py"})]

for name, df in [("코드 먼저", code_first), ("lockfile 먼저", lock_first)]:
    print(f"[{name}] train.py 수정 -> 다시 실행:", rebuilt(df, {"train.py"}))

[코드 먼저] train.py 수정 -> 다시 실행: ['COPY . /app', 'RUN uv sync --locked']
[lockfile 먼저] train.py 수정 -> 다시 실행: ['COPY . /app']

코드를 먼저 복사하면 train.py 한 줄을 고칠 때마다 의존성 설치(수 분, PyTorch라면 수 GB 다운로드)가 다시 실행된다. lockfile을 먼저 복사하면 의존성 layer는 cache에서 재사용되고 코드 복사만 다시 일어난다. (이 흉내에서는 생략했지만, 실제 Dockerfile에서는 코드를 복사한 뒤 프로젝트 자신을 설치하는 짧은 uv sync 줄이 뒤따른다.) RUN --mount=type=cache는 BuildKit 기능으로, 패키지 다운로드 cache를 빌드 사이에 보존하되 image에는 넣지 않는다.

.dockerignore. COPY . .은 빌드 context(보통 저장소 루트) 전체를 복사한다. .venv, .git, 데이터, 결과 디렉터리가 섞여 들어가지 않도록 .dockerignore에 적어 둔다. 로컬의 .venv가 image에 복사되면 image가 커질 뿐 아니라, 다른 경로에서 만든 가상환경이라 제대로 동작하지도 않는다(3.3장).

multi-stage build. 빌드에만 필요한 도구(컴파일러, CUDA toolkit의 devel 변형)와 실행에 필요한 것을 단계로 나눈다. 첫 단계(FROM ... AS builder)에서 extension을 컴파일하고, 두 번째 단계에서 가벼운 runtime image에 결과물만 COPY --from=builder로 가져온다. 실행 image가 작아지고, 컴파일러 같은 불필요한 도구가 배포되지 않는다.

데이터와 결과

컨테이너의 원칙은 image에는 환경만, 데이터와 결과는 밖에다. 데이터를 image에 넣으면 image가 데이터 크기만큼 커지고, 데이터가 바뀔 때마다 다시 빌드해야 하며, image를 공유하는 순간 데이터도 함께 퍼진다. 결과를 컨테이너의 쓰기 layer에 저장하면 컨테이너와 함께 사라진다.

컨테이너 밖의 저장소를 연결하는 방법은 두 가지다.

연구에서는 bind mount가 기본이다. 결과가 호스트의 프로젝트 디렉터리에 바로 남고, 백업·버전 관리·다른 도구와의 연동이 쉽기 때문이다. 실행 예는 다음과 같다(집필 시점 예시).

docker run --rm \
    --user "$(id -u):$(id -g)" \
    -v /data/shared/dataset-v3:/data:ro \
    -v "$PWD/outputs":/outputs \
    -w /app \
    -e OUTPUT_DIR=/outputs \
    lab/proj@sha256:<digest> python train.py --data /data

• 데이터는 읽기 전용(:ro)으로 마운트한다. 학습 코드의 버그가 원본 데이터를 덮어쓰는 사고를 막는다.
• 결과 디렉터리는 쓰기 가능으로 마운트하고, 코드는 출력 경로를 환경변수나 인자로 받는다. 코드 안에 컨테이너 경로를 하드코딩하지 않으면 같은 코드가 컨테이너 밖에서도 돈다.
• -w(working directory)를 명시해, 상대 경로가 어디를 기준으로 하는지 분명히 한다.
• --rm은 끝난 컨테이너를 자동으로 지운다. 결과가 마운트한 경로에 있으므로 안심하고 지울 수 있다. 반대로 말하면, --rm을 쓰면서 마운트하지 않은 경로에 결과를 쓰면 모두 사라진다.

GPU 사용

컨테이너는 호스트 kernel을 공유하므로, GPU 드라이버의 kernel 모듈도 호스트의 것을 쓴다. 컨테이너 안에서 GPU를 쓰려면 호스트에 NVIDIA Container Toolkit을 설치하고 Docker가 그것을 쓰도록 설정한다. 그러면 docker run --gpus ...로 실행할 때 툴킷이 호스트 드라이버의 사용자 공간 라이브러리(libcuda.so 등)와 GPU 장치 파일을 컨테이너에 넣어 준다(설치 절차는 공식 설치 가이드를 따른다).

# 모든 GPU를 쓴다 / 특정 GPU만 쓴다 (집필 시점 예시)
docker run --rm --gpus all lab/proj nvidia-smi
docker run --rm --gpus '"device=0,1"' lab/proj python train.py

계층으로 보면 역할이 분명하다(3.1장).

따라서 규칙은 3.1장과 같다. image 안의 CUDA runtime 버전이 호스트 드라이버가 지원하는 범위 안에 있어야 한다. image에 드라이버를 설치하지 않는다. 호스트에 CUDA toolkit이 있을 필요도 없다. 호스트 드라이버가 CUDA 12.x까지만 지원하는데 CUDA 13 계열 PyTorch가 든 image를 쓰면, 컨테이너 안에서도 똑같이 실패한다. 컨테이너는 이 규칙을 없애지 않고, 규칙을 지켜야 하는 경계를 "호스트 드라이버 ↔ image"로 옮길 뿐이다.

실무 이슈

사용자 권한(UID/GID). 컨테이너 안의 프로세스는 기본적으로 root(UID 0)로 실행된다. 이 상태로 bind mount한 디렉터리에 결과를 쓰면, 호스트에서 그 파일의 소유자가 root가 되어 일반 사용자가 지우거나 고칠 수 없다. --user "$(id -u):$(id -g)"로 호스트 사용자와 같은 UID·GID로 실행하면 이 문제가 없다. 이때 컨테이너 안에 그 UID의 홈 디렉터리가 없어 일부 도구가 cache를 쓸 곳을 찾지 못할 수 있으므로, HOME이나 cache 경로를 쓰기 가능한 곳으로 지정한다.

공유 서버에서는 보안 문제도 있다. docker 그룹에 속한 사용자는 호스트의 아무 디렉터리나 root 권한으로 마운트할 수 있으므로, 사실상 root와 같은 권한을 가진다. 여러 사람이 쓰는 서버라면 rootless 모드의 Docker, Podman, 또는 다음 절의 Apptainer처럼 사용자 권한으로 실행되는 도구를 검토한다.

shared memory(--shm-size). PyTorch의 DataLoader는 num_workers > 0일 때 worker 프로세스가 만든 batch를 shared memory(/dev/shm)를 통해 주 프로세스로 넘긴다. Docker 컨테이너의 /dev/shm 기본 크기는 64 MiB다. worker마다 prefetch_factor개(기본값 2)의 batch를 미리 준비하므로, 대기 중인 batch가 차지하는 양을 어림할 수 있다.

B, C, H, W = 64, 3, 224, 224                    # 이미지 batch (B, C, H, W)
bytes_per_batch = B * C * H * W * 4             # float32
num_workers, prefetch_factor = 8, 2             # worker마다 미리 준비해 두는 batch 수
in_flight = num_workers * prefetch_factor

need_mib = in_flight * bytes_per_batch / 2**20
print(f"batch 하나: {bytes_per_batch / 2**20:.1f} MiB")
print(f"동시에 대기하는 batch: {in_flight}개 -> 약 {need_mib:.0f} MiB")
print(f"Docker 기본 /dev/shm 64 MiB의 {need_mib / 64:.1f}배")

batch 하나: 36.8 MiB
동시에 대기하는 batch: 16개 -> 약 588 MiB
Docker 기본 /dev/shm 64 MiB의 9.2배

흔한 이미지 학습 설정 하나만으로 기본값의 9배가 필요하다. 이 어림은 label과 내부 오버헤드를 빼고 계산한 하한이다. 부족하면 worker가 bus error나 shared memory 관련 오류로 죽는다. --shm-size=16g처럼 넉넉히 늘리거나, 호스트의 IPC 네임스페이스를 공유하는 --ipc=host를 쓴다.

네트워크와 포트. 컨테이너 안의 Jupyter나 TensorBoard에 접속하려면 포트를 연결한다. -p 8888:8888은 호스트의 모든 네트워크 인터페이스에 포트를 연다. Docker가 추가하는 방화벽 규칙 때문에 호스트 방화벽 설정과 상관없이 외부에서 접근 가능해질 수 있다. 공유 서버에서는 -p 127.0.0.1:8888:8888로 localhost에만 열고, SSH 터널(2.3장)로 접속한다.

개발 컨테이너와 HPC

devcontainer. 편집기(VS Code 등)가 컨테이너 안에서 개발 환경을 여는 규격이다. 저장소의 .devcontainer/devcontainer.json에 사용할 Dockerfile과 실행 옵션을 적어 두면, 새 구성원이 저장소를 열 때 같은 컨테이너가 만들어진다(집필 시점 예시).

{
  "name": "proj",
  "build": { "dockerfile": "../Dockerfile" },
  "runArgs": ["--gpus=all", "--shm-size=16g"],
  "mounts": ["source=/data/shared,target=/data,type=bind,readonly"]
}

연구용 Dockerfile 하나를 실행 image와 개발 환경에 함께 쓰면, "개발할 때와 실행할 때 환경이 다르다"는 문제가 줄어든다.

Apptainer(Singularity). 대부분의 HPC 클러스터는 보안상 Docker daemon을 허용하지 않고, 대신 Apptainer(이전 이름 Singularity)를 제공한다. Apptainer는 사용자 권한으로 컨테이너를 실행하고, image를 SIF라는 단일 파일로 다룬다. Docker image를 변환해 쓸 수 있으므로, Docker로 만든 연구 image를 클러스터에서 그대로 실행할 수 있다(집필 시점 예시. 클러스터의 안내 문서를 먼저 확인한다).

# registry의 Docker image를 SIF 파일로 변환
apptainer build proj.sif docker://registry.example.org/lab/proj@sha256:<digest>
# GPU(--nv)를 쓰고, 데이터 디렉터리를 연결해 실행
apptainer exec --nv --bind /scratch/me/data:/data proj.sif python train.py --data /data

Docker와 기본 동작이 다른 점이 있다. Apptainer는 기본적으로 사용자의 홈 디렉터리와 현재 디렉터리 등을 컨테이너에 자동으로 연결하고, 호스트 사용자 그대로 실행된다. 그래서 UID 문제는 없지만, 홈 디렉터리의 ~/.local에 있는 패키지가 컨테이너 안의 Python에 섞여 들 수 있다(3.3장의 사용자 site-packages 문제). 컨테이너 안에서도 python -m site로 확인한다.

재현 가능한 빌드

Dockerfile이 같아도 나중에 다시 빌드한 image는 다를 수 있다. 시간에 따라 바뀌는 입력이 있기 때문이다.

• base image tag: python:3.12-slim은 보안 패치가 나올 때마다 새 image를 가리킨다.
• 시스템 패키지: apt-get update && apt-get install은 빌드 시점의 최신 패키지를 받는다.
• 언어 패키지: lockfile 없이 설치하면 빌드 시점의 최신 버전이 들어온다.
• 외부 다운로드: curl로 받는 파일, latest tag의 도구 image(ghcr.io/astral-sh/uv:latest 등).

재현이 중요한 image는 이 입력들을 고정한다.

1. FROM과 COPY --from의 image를 digest로 고정한다: FROM python:3.12-slim@sha256:<digest>. tag를 함께 적어 두면 사람이 읽기 쉽다.
2. Python 패키지는 lockfile로 설치한다(uv sync --locked).
3. 시스템 패키지는 꼭 필요한 것만 설치하고, 가능하면 버전을 명시한다.
4. 빌드 기록을 남긴다. 결과 image의 digest, 빌드한 git 커밋, 빌드 날짜를 실험 기록에 함께 적는다. 커밋 해시를 image에 label로 넣어 두면 image만 보고도 출처를 찾을 수 있다.

GIT_SHA=$(git rev-parse HEAD)
docker build --label org.opencontainers.image.revision="$GIT_SHA" -t lab/proj:"${GIT_SHA:0:8}" .
docker push lab/proj:"${GIT_SHA:0:8}"
docker image inspect --format '{{json .RepoDigests}}' lab/proj:"${GIT_SHA:0:8}"   # 기록할 digest

완벽한 비트 단위 재현까지는 필요하지 않은 경우가 많다. 연구에서 중요한 것은 나중에 같은 image를 다시 실행할 수 있는가이고, 그것은 빌드 결과를 digest로 registry에 보관하는 것으로 대부분 해결된다. 다시 빌드하는 능력은 그 image가 사라졌을 때를 위한 보험이다.