HOWTO · Docker
Docker 컨테이너에 호스트 디렉터리 마운트하기
호스트 디렉터리를 Docker 컨테이너에 마운트하는 방법을 알아봅니다.
이 페이지의 내용
바인드 마운트는 호스트의 디렉터리를 Docker 컨테이너 내부 경로에 연결합니다. 개발 중인 소스 코드처럼 컨테이너에서 특정 호스트 디렉터리의 파일을 읽거나 수정해야 할 때 사용할 수 있습니다. 아래 예제에서는 먼저 호스트 디렉터리와 파일을 준비한 뒤, Docker 명령으로 해당 디렉터리를 Alpine 셸에서 사용할 수 있게 합니다. Docker 명령은 사용 방법을 보여 주기 위한 예시이며, 이 작성 단계에서 실행하지 않았습니다.
바인드 마운트로 호스트 디렉터리를 Docker 컨테이너에 마운트
바인드 마운트는 선택한 호스트 경로를 컨테이너 경로에 연결합니다. Docker가 관리하는 볼륨과 달리, 바인드 마운트의 원본은 호스트의 특정 위치입니다. 해당 디렉터리의 파일을 변경하면 컨테이너의 마운트 지점에서도 변경 사항을 볼 수 있습니다. 애플리케이션에서도 파일 변경을 확인할 수 있지만, 핫 리로드가 되려면 애플리케이션이 파일을 감시하거나 다시 불러와야 합니다.
-v 또는 --volume으로 호스트 디렉터리 마운트
다음 Python 예제는 site라는 호스트 디렉터리를 만들고 그 안에 파일을 기록한 다음 파일 이름을 출력합니다. Docker를 실행할 디렉터리에서 이 코드를 실행하세요.
from pathlib import Path
site = Path("site")
site.mkdir(exist_ok=True)
(site / "hello.txt").write_text("Hello from the host.\n")
print("\n".join(sorted(path.name for path in site.iterdir())))
hello.txt
호스트 파일이 준비되면 docker run --rm -it --volume "$PWD/site:/site" alpine:3.20 sh 명령으로 컨테이너를 시작해 /site에서 확인할 수 있습니다. 볼륨 값은 호스트-경로:컨테이너-경로[:옵션] 형식입니다. 여기서 $PWD/site는 호스트 디렉터리이고 /site는 컨테이너 안에서 보이는 경로입니다. 선택 사항인 ro를 붙이면 마운트가 읽기 전용이 됩니다. 짧은 플래그 -v와 긴 플래그 --volume은 같은 구문을 사용하므로, -v "$PWD/site:/site:ro"는 읽기 전용으로 마운트하는 예입니다.
컨테이너 셸이 실행 중일 때 호스트에서 touch "$PWD/site/new-file.txt"를 실행해 새 파일을 만드세요. 컨테이너 프롬프트에서 ls /site/new-file.txt를 실행하면 호스트에서 만든 파일이 마운트 지점에도 보이는지 확인할 수 있습니다. 쓰기가 허용된 마운트라면 /site에서 만든 파일도 호스트 디렉터리에 기록됩니다. 읽기 전용 마운트에서는 컨테이너가 파일을 읽을 수 있지만, 해당 마운트를 통해 파일을 변경할 수는 없습니다.
-v와 --volume은 호스트 원본 디렉터리가 없으면 디렉터리로 새로 만듭니다. 컨테이너를 사용하기 전에 생성된 호스트 경로를 확인하세요. 경로를 잘못 입력하면 새 빈 디렉터리가 만들어져 예상한 파일이 없는 것처럼 보일 수 있습니다.
--mount로 호스트 디렉터리 마운트
--mount 형식에서는 각 설정을 쉼표로 구분된 키-값 항목으로 지정합니다. 같은 예제를 사용하려면 docker run --rm -it --mount "type=bind,source=$PWD/site,target=/site" alpine:3.20 sh를 실행하세요. type=bind는 바인드 마운트를 선택하고, source는 호스트 디렉터리이며, target은 컨테이너 안의 경로입니다. 마운트를 통한 쓰기를 막으려면 항목에 readonly를 추가하세요. 원본과 대상은 항목의 위치가 아니라 키로 구분됩니다.
-v 및 --volume과 달리 --mount는 바인드 마운트의 원본 경로가 없으면 오류를 표시합니다. 컨테이너를 시작하기 전에 호스트 디렉터리를 만들고 경로가 올바른지 확인하세요. 경로에 쉼표가 들어가면 쉼표로 구분하는 마운트 구문을 다룰 때 추가로 주의해야 합니다. 적절한 호스트 경로를 선택하거나 사용 중인 플랫폼의 Docker 마운트 구문을 확인하세요.
바인드 마운트를 사용하면 컨테이너가 선택한 호스트 경로에 접근할 수 있습니다. 작업에 필요한 디렉터리만 마운트하고 민감한 파일을 노출하지 않도록 하며, 컨테이너에 쓰기 권한이 필요하지 않다면 읽기 전용으로 설정하세요. 호스트 경로 공유와 권한은 시스템의 Docker 설정에 따라서도 달라질 수 있습니다.
결론
간결한 콜론 구분 형식에는 -v 또는 --volume을, 명시적인 키-값 항목에는 --mount를 사용하세요. 두 형식 모두 호스트 디렉터리를 컨테이너 경로에서 사용할 수 있게 합니다. -v는 존재하지 않는 원본 디렉터리를 만들 수 있지만, --mount를 쓰려면 원본이 미리 있어야 합니다. 컨테이너에서 호스트의 특정 경로를 사용해야 한다면 바인드 마운트를 선택하세요. 특정 호스트 디렉터리와 독립적으로 Docker가 관리할 애플리케이션 데이터에는 Docker 관리 볼륨이 더 적합할 수 있습니다.