Docker에서 Ollama 설치하기: CPU·GPU·볼륨·API 확인

Ollama를 Docker에서 실행하면 달라지는 점

일반적인 Ollama는 로컬 서비스처럼 동작합니다. 명령으로 런타임을 시작하고 모델 파일은 컴퓨터에 저장되며 클라이언트는 11434 포트를 호출합니다. Docker는 자체 파일 시스템, 프로세스 네임스페이스, 네트워크 규칙과 수명 주기를 가진 컨테이너 안에 이 서비스를 넣습니다. 반복 가능한 배포에는 편리하지만 /root/.ollama를 볼륨으로 보존하지 않으면 컨테이너 안에서 받은 모델이 컨테이너 삭제와 함께 사라질 수 있습니다.

따라서 작동하는 Docker 명령 하나만으로는 구성이 끝나지 않습니다. Docker를 유일한 Ollama 런타임으로 사용할지, 호스트 애플리케이션이나 다른 컨테이너가 호출할지, 모델 다운로드가 업그레이드 후에도 남아야 하는지를 결정해야 합니다. OpenCode, MCP 호스트, 웹 UI 또는 원격 클라이언트를 추가하기 전에 이 경계를 분명하게 기록하세요.

CPU, NVIDIA GPU 또는 AMD GPU 선택

네트워크, 볼륨 또는 새 호스트를 확인할 때는 먼저 CPU 경로를 사용하세요. 변경 요소가 가장 적어 모델 로딩 시간과 응답 속도를 비교할 기준을 만들 수 있습니다. API가 작동한 뒤에는 다른 런타임에서 복사한 무작위 Docker 옵션을 더하지 말고 호스트에 맞는 가속기 명령으로 전환하세요.

NVIDIA 컨테이너는 일반적으로 정상적인 호스트 드라이버와 NVIDIA Container Toolkit에 의존합니다. AMD 배포는 다른 이미지 태그와 장치 매핑을 사용할 수 있으며 운영체제, 런타임과 최신 Ollama 안내에 따라 지원 범위가 달라집니다. GPU는 최적화 계층으로 취급하세요. 엔드포인트, 볼륨 경로와 기본 상태 확인은 바뀌지 않아야 합니다.

docker version

docker run --rm --gpus=all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi

모델을 보존할 저장 볼륨 만들기

이름 있는 볼륨은 Docker에서 Ollama를 설정할 때 가장 쉬운 기본값입니다. 저장 위치를 Docker가 관리하므로 모델 파일을 직접 옮기지 않고 컨테이너를 교체할 수 있습니다. 공식 이미지는 /root/.ollama 아래에 Ollama 데이터를 저장하므로 항상 같은 위치에 볼륨을 마운트하세요. 첫 실행과 업그레이드에서 다른 볼륨을 만들면 새 모델 라이브러리가 생깁니다.

특정 호스트 디렉터리의 디스크 사용량을 확인하거나 백업하거나 특정 드라이브에 모델을 두려면 바인드 마운트를 사용할 수 있습니다. 대신 권한과 경로를 더 많이 결정해야 합니다. 첫 배포라면 이름 있는 볼륨이 설명하기 쉽고 실수로 망가뜨릴 가능성도 낮습니다.

docker volume create ollama-data

docker run -d --name ollama -p 11434:11434 -v ollama-data:/root/.ollama ollama/ollama

docker exec -it ollama ollama pull <model-name>

컨테이너 시작 및 API 확인

docker run이 컨테이너 ID를 반환하면 큰 모델을 받기 전에 상태를 확인하세요. docker ps로 프로세스가 계속 실행 중인지 확인하고 docker logs에서 포트, 권한 또는 런타임 오류를 찾습니다. 그 다음 호스트에서 /api/tags를 호출하세요. tags 응답이 성공해도 HTTP 엔드포인트에 접근할 수 있다는 뜻일 뿐, 모든 모델이 로드되거나 모든 클라이언트에 권한이 있다는 뜻은 아닙니다.

두 번째 확인으로 작은 모델 요청을 하나 실행하세요. 이를 통해 정상적인 HTTP 리스너와 실제 모델 경로를 구분할 수 있습니다. API는 응답하지만 모델 요청이 실패하면 네트워크 설정을 바꾸기 전에 모델 이름, 디스크 여유 공간, 메모리와 컨테이너 로그를 확인하세요.

1. 프로세스 확인

   컨테이너가 Up 상태이고 공개 포트가 의도한 포트인지 확인합니다.

2. 엔드포인트 확인

   11434 포트를 공개한 같은 컴퓨터에서 /api/tags를 요청하고 상태 코드를 기록합니다.

3. 모델 확인

   작은 모델을 받거나 사용한 뒤 편집기 또는 에이전트를 연결하기 전에 안전한 프롬프트를 하나 실행합니다.

docker ps --filter name=ollama

docker logs ollama --tail 100

curl http://127.0.0.1:11434/api/tags

docker exec -it ollama ollama list

localhost를 혼동하지 않고 호스트 앱 연결

올바른 Ollama URL은 클라이언트가 실행되는 위치에 따라 달라집니다. Docker가 포트를 공개한 같은 호스트의 데스크톱 앱은 일반적으로 http://127.0.0.1:11434를 호출할 수 있습니다. 같은 Docker 네트워크의 다른 컨테이너는 Compose 서비스 이름과 포트, 예를 들어 http://ollama:11434를 사용해야 합니다. 컨테이너 안에서 127.0.0.1은 그 컨테이너 자체이며 Windows, macOS 또는 Linux 호스트를 자동으로 가리키지 않습니다.

원격 클라이언트에는 명시적으로 보호한 주소와 방화벽 규칙을 사용하세요. 테스트 앱을 연결하기 위해 11434 포트를 공용 인터넷에 공개하지 마세요. 원격 엔드포인트가 필요하다면 경로, 인증 또는 사설 네트워크 경계와 접근을 허용할 정확한 모델 서비스를 문서화합니다.

모델, 컨텍스트와 외부 공개 범위 안전하게 유지

Docker가 Ollama 서비스를 자동으로 비공개로 만들어 주지는 않습니다. 명령과 호스트 기본값에 따라 공개 포트가 모든 인터페이스에 바인딩될 수 있습니다. 호스트 전용 테스트라면 다른 컴퓨터가 접근할 필요가 없을 때 -p 127.0.0.1:11434:11434처럼 루프백 바인딩을 우선하세요. Compose 서비스가 내부에서 API를 사용한다면 사설 네트워크에 두고 꼭 필요하지 않은 호스트 포트는 공개하지 않습니다.

모델 컨텍스트 길이, 동시성 및 GPU 메모리는 컨테이너가 사용하는 RAM과 VRAM을 바꿀 수 있습니다. 한 번에 하나의 변수만 늘리고 docker stats, 호스트 메모리와 모델 응답을 관찰하세요. 이미지, 셸 기록, 스크린샷과 버전 관리하는 Compose 파일에 비밀을 넣지 마세요. 로컬 모델 엔드포인트와 외부 검색 도구는 서로 다른 개인정보 경계를 가집니다.

상태, GPU, 볼륨과 API 오류 해결

Docker에서 Ollama 배포가 실패하면 한 번에 한 계층만 바꾸세요. 먼저 Docker 자체가 간단한 컨테이너를 시작할 수 있는지 확인하고, 다음으로 Ollama 컨테이너가 계속 실행되는지 확인합니다. 그 다음 볼륨, API, 모델, 마지막으로 클라이언트 애플리케이션을 점검하세요. 오류가 날 때마다 전체 명령을 바꾸면 실제로 실패한 경계가 보이지 않습니다.

GPU 오류는 Ollama API보다 호스트 런타임에 있는 경우가 많습니다. GPU가 전달되지 않았거나 드라이버가 호환되지 않거나 선택한 이미지가 호스트와 맞지 않으면 컨테이너가 /api/tags에 응답하면서도 CPU를 사용할 수 있습니다. 컨테이너를 다시 만든 뒤 모델이 사라졌다면 다시 받기 전에 docker inspect 결과와 마운트 대상 경로를 비교하세요.

docker inspect ollama

docker stats ollama

docker stop ollama && docker rm ollama