Docker, Ollama, 그리고 Open WebUI를 이용한 자체 호스팅 LLM 구축

클라우드 AI는 편리합니다. 브라우저를 열고, 프롬프트(prompt)를 입력하면 답변을 얻을 수 있죠. 하지만 저를 괴롭히는 세 가지 문제가 있습니다. 월말에 깜짝 놀라게 만드는 API 비용, 작업 도중에 발생하는 속도 제한(rate limits), 그리고 내가 나누는 모든 대화가 타인의 서버에 저장되고 있다는 사실입니다.

저는 수개월 동안 홈랩(homelab)에서 로컬 LLM을 실행해 왔습니다. 10년 된 Xeon 서버부터 150달러짜리 미니 PC까지 말이죠. 그중 가장 기억에 남는 설정은 무엇일까요? 바로 Docker, Ollama, 그리고 Open WebUI의 조합입니다. 세 가지 요소, 5분이면 충분합니다. 당신만의 프라이빗 ChatGPT를 가질 수 있습니다.

보안 강화(security hardening), API 액세스, GPU 패스스루(GPU passthrough), 그리고 여러분이 이미 사용 중일 도구들과의 통합까지 포함하여 제대로 설정하는 방법을 소개합니다.

구축하게 될 내용

이 포스트를 다 읽을 때쯤 여러분은 다음을 갖게 됩니다:

• Ollama가 Docker에서 실행됨 — LLM(Ollama 라이브러리에 있는 Gemma, Llama, Phi, Mistral 등 무엇이든)을 가져오고 서빙함
• Open WebUI가 Docker에서 실행됨 — Ollama와 통신하는 깔끔한 ChatGPT 스타일의 인터페이스
• 단 하나의 명령어로 모든 것을 시작하는 단일 docker-compose.yml 파일
• 로컬 모델 추론(inference)을 통해 완전히 여러분의 하드웨어에서 실행되며, 클라우드 LLM 제공업체로 프롬프트가 전송되지 않는 모델들
• 어떤 OpenAI 호환 도구라도 사용할 수 있는 API 액세스

Docker가 설치되어 있어야 하며 최소 8GB의 여유 RAM이 필요합니다. 그게 전부입니다. 만약 Docker가 처음이라면, 제가 작성한 컨테이너가 내부적으로 실제로 어떻게 작동하는지에 대한 심층 분석 글을 참고하세요. 이 가이드를 위해 반드시 읽어야 하는 것은 아니지만, docker run이 실제로 무엇을 하는지 알면 문제 해결(troubleshooting)이 훨씬 덜 미스터리해질 것입니다. ## 1단계: Docker에서의 Ollama Ollama는 모델을 다운로드하고 실행하는 엔진입니다. Ollama는 11434 포트에서 REST API를 노출하며, 이를 통해 모든 클라이언트(Open WebUI 포함)가 통신할 수 있습니다.

내부적으로 Ollama는 CPU 추론 (inference)을 실용적으로 만들어주는 C++ 추론 엔진 (inference engine)인 llama.cpp를 감싸고(wrap) 있습니다. 공식 Ollama Docker 이미지는 Docker Hub의 ollama/ollama에 있습니다. 이를 실행하기 위한 가장 간단한 명령어는 다음과 같습니다:

docker run -d \
  --name ollama \
  -p 127.0.0.1:11434:11434 \
...

명령어를 자세히 분석해 보겠습니다:

• -d는 백그라운드에서 실행 (데몬 모드, detached mode)
• --name ollama는 나중에 참조할 수 있도록 컨테이너에 고정된 이름을 부여합니다.
• -p 127.0.0.1:11434:11434는 Ollama의 API를 localhost에만 바인딩(bind)합니다. 이는 동일한 머신에 있는 Open WebUI와 API 클라이언트가 Ollama에 접속하는 방식입니다.
• -v ollama_data:/root/.ollama는 다운로드한 모델을 위한 이름이 지정된 Docker 볼륨 (volume)을 생성합니다. 이것이 없으면 컨테이너를 다시 생성할 때마다 모든 모델을 다시 다운로드해야 합니다. 볼륨을 사용하면 컨테이너가 재시작되어도 모델이 유지됩니다.
• --restart unless-stopped는 재부팅 후에도 Ollama가 다시 실행되도록 보장합니다.

컨테이너가 시작될 때까지 몇 초간 기다린 후, 다음 명령어로 확인하세요:

docker ps | grep ollama

상태가 Up인 ollama/ollama 컨테이너가 보여야 합니다.

2단계: 첫 번째 모델 가져오기 (Pull)

Ollama 컨테이너는 실행 중이지만, 아직 모델이 없는 빈 상태입니다. 컨테이너 내부에서 ollama pull을 실행하여 모델을 가져올 수 있습니다:

docker exec -it ollama ollama pull llama3.2:3b

이 명령은 Meta의 Llama 3.2 3B 모델을 다운로드합니다. 양자화 (quantized)되었을 때 크기는 약 2GB입니다. 거의 모든 환경에서 실행할 수 있을 만큼 작지만 (저는 24GB RAM을 탑재한 150달러 상당의 BMAX Pro 8에서도 유사한 모델을 실행해 보았습니다), 실제 작업에 사용할 수 있을 만큼 충분히 똑똑합니다.

다운로드되는 동안 다음과 같은 일이 일어납니다: Ollama는 모델 레지스트리 (registry)에서 GGUF 양자화 가중치 (quantized weights)를 가져와 컨테이너 내부의 /root/.ollama/models에 저장합니다 (이 경로는 호스트의 ollama_data 볼륨과 매핑됩니다). 다운로드가 완료되면 모델은 즉시 서비스를 제공할 준비가 됩니다.

가져오기가 완료되면 테스트해 보세요:

docker exec -it ollama ollama run llama3.2:3b "Explain what a container is in one sentence"

터미널에 스트리밍 응답 (streaming response)이 나타나는 것을 볼 수 있습니다. Ollama가 정상적으로 작동하고 있습니다.

사용자의 하드웨어 사양에 따라 다운로드(pull)할 만한 가치가 있는 모델들은 다음과 같습니다:

RAM이 제한적인 기기라면 3B–4B 범위를 유지하세요. 이 모델들은 빠르며 일상적인 작업에서 놀라울 정도로 유능합니다. 저는 10년 된 Xeon 프로세서부터 150달러짜리 미니 PC에 이르기까지 다양한 환경에서 모델들을 벤치마크(benchmark)해 보았는데, 초당 토큰 수 (token-per-second) 수치가 여러분을 놀라게 할 수도 있습니다.

어떤 모델이 로드되어 있는지, 그리고 어디에서 실행 중인지 (GPU vs CPU) 확인하려면 다음 명령어를 사용하세요:

docker exec -it ollama ollama ps

Step 3: Open WebUI — ChatGPT 스타일의 인터페이스

Ollama의 API는 스크립트 작성에 매우 유용합니다. 하지만 사람이 직접 사용하기에는 어떨까요? 여러분은 채팅 인터페이스를 원할 것입니다. Open WebUI는 업계 표준(gold standard)입니다. 이는 ChatGPT와 유사한 외관과 사용감을 제공하면서도 여러분의 로컬 Ollama 인스턴스와 통신하는, 기능이 풍부한 셀프 호스팅 (self-hosted) 웹 앱입니다.

Open WebUI는 GitHub Container Registry를 통해 Docker 이미지로 제공됩니다: ghcr.io/open-webui/open-webui:main.

명령어는 다음과 같습니다:

docker run -d \
  --name open-webui \
  -p 127.0.0.1:3000:8080 \
...

여기서 핵심 플래그는 --add-host=host.docker.internal:host-gateway입니다. 이를 통해 Open WebUI 컨테이너가 호스트 머신의 네트워크, 즉 11434 포트에서 실행 중인 Ollama에 접근할 수 있게 됩니다. 이 설정이 없으면 컨테이너는 별도의 컨테이너에서 실행 중인 Ollama를 볼 수 없습니다.

설치가 완료되면 브라우저를 열고 http://localhost:3000으로 이동하세요. 관리자 계정을 생성하면(가장 먼저 생성한 계정이 관리자가 됩니다) 채팅 화면으로 이동하게 됩니다. Open WebUI는 로컬 Ollama 인스턴스를 자동으로 감지해야 합니다. 만약 감지되지 않는다면, Settings(설정) → Connections(연결)로 이동하여 Ollama Base URL (http://host.docker.internal:11434)을 확인하세요.

모델 드롭다운 메뉴에서 llama3.2:3b가 보여야 합니다. 이를 선택하고 채팅을 시작하세요.

4단계: Docker Compose — 하나의 파일, 하나의 명령

두 개의 별도 docker run 명령어를 실행하는 것도 가능하지만, 번거롭습니다. Docker Compose를 사용하면 두 서비스를 하나의 파일에 정의하고 함께 관리할 수 있습니다. 더 중요한 점은, 서비스 이름을 통해 컨테이너끼리 서로 통신할 수 있게 해주므로 --add-host와 같은 편법이 필요 없다는 것입니다.

docker-compose.yml 파일을 생성하세요:

services:
  ollama:
    image: ollama/ollama:latest
...

OLLAMA_BASE_URL=http://ollama:11434 부분에 주목하세요. Compose 네트워크 내부에서는 컨테이너들이 서비스 이름으로 서로에게 접근할 수 있습니다. host-gateway 트릭이 필요하지 않습니다.

파일을 저장한 후 다음을 실행하세요:

docker compose up -d

끝났습니다. 두 컨테이너가 모두 시작됩니다. 모델은 Docker 볼륨(volumes)에 영구 저장됩니다. 컴퓨터를 재부팅해도 모든 것이 그대로 유지됩니다. 언제든지 새로운 모델을 가져올(pull) 수 있습니다:

docker exec -it ollama ollama pull llama3.2:3b

5단계: GPU 가속 (GPU Acceleration)

CPU 추론 (Inference)도 작동은 합니다. 저도 매일 제 Xeon 프로세서에서 그렇게 하고 있으니까요. 하지만 GPU가 있다면, 당연히 GPU를 활용하고 싶을 것입니다. 적당한 사양의 하드웨어에서도 토큰 생성 속도가 ~10 tok/s (CPU)에서 ~50+ tok/s (GPU)로 급격히 상승합니다.

Nvidia GPU

Nvidia Container Toolkit을 설치하세요:

sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

그 다음, compose 파일에서 deploy: 블록의 주석을 해제하고 재시작하세요:

docker compose down && docker compose up -d

Compose 대신 단독 docker run 방식을 사용 중이라면, --gpus=all 옵션을 추가하세요:

docker run -d \
  --name ollama \
  -p 127.0.0.1:11434:11434 \
...

Ollama는 CUDA를 자동으로 감지합니다. 모델을 로드한 후 docker exec -it ollama ollama ps를 실행해 보세요. 패스스루 (Passthrough)가 제대로 작동하고 있다면 100% GPU라고 표시될 것입니다.

AMD GPU (ROCm)

AMD 그래픽 카드의 경우, ROCm 태그가 붙은 Ollama 이미지를 사용하세요:

ollama:
  image: ollama/ollama:rocm
  devices:
...

먼저 호스트에서 rocminfo를 사용하여 GPU 지원 여부를 확인하세요. ROCm은 v7 드라이버와 특정 GFX 타겟을 요구하므로, 모든 AMD GPU가 지원되는 것은 아닙니다.

Intel / Vulkan

표준 ollama/ollama 이미지는 Intel GPU를 위한 Vulkan 지원을 포함하고 있습니다. 호스트에 Mesa Vulkan 드라이버를 설치하면 (sudo apt install mesa-vulkan-drivers) Ollama가 이를 인식합니다. 필요한 경우 OLLAMA_VULKAN=0으로 비활성화할 수 있습니다.

LLM 추론 (Inference)을 위한 핵심 통찰: 추론은 연산량 제한 (Compute-bound)이 아니라 메모리 대역폭 제한 (Memory-bandwidth-bound)을 받습니다. CPU 추론은 충분한 RAM 대역폭 (DDR4/DDR5 멀티 채널)이 있다면 잘 작동합니다. 128 GB의 DDR3를 갖춘 중고 서버는 클라우드 서비스에 필적하는 26B 모델을 모두 CPU만으로 구동할 수 있습니다.

API 사용 — 네이티브 및 OpenAI 호환

이 지점에서 이 스택의 강력함이 드러납니다. Ollama는 두 가지 API 인터페이스를 제공합니다. 완전한 제어를 위한 네이티브 REST API와, OpenAI 규격을 따르는 모든 도구에서 즉시 사용할 수 있는 OpenAI 호환 엔드포인트입니다.

네이티브 REST API

네이티브 API는 http://localhost:11434/api에 위치합니다. 다음은 시스템 프롬프트 (system prompt)와 온도 조절 (temperature control)을 포함한 채팅 완성 (chat completion) 예시입니다:

curl http://localhost:11434/api/chat -d '{
  "model": "llama3.2:3b",
  "messages": [
...

구조화된 출력 (Structured output, JSON schema mode) — 모델이 예측 가능한 형태로 데이터를 반환하도록 강제합니다:

curl http://localhost:11434/api/chat -d '{
  "model": "llama3.2:3b",
  "messages": [{"role": "user", "content": "List 3 IGCSE CS topics with difficulty ratings."}],
...

이는 자동화에 매우 유용합니다. 장황한 문단이 아닌, 보장된 JSON을 받을 수 있기 때문입니다.

기타 유용한 네이티브 엔드포인트 (native endpoints):

OpenAI 호환 엔드포인트 (OpenAI-Compatible Endpoints)

OpenAI API를 지원하는 모든 도구의 주소를 API 키 없이 http://localhost:11434/v1로 지정하면 됩니다:

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
...

지원되는 OpenAI 호환 엔드포인트에는 채팅 완성 (Chat Completions), 완성 (Completions), 모델 목록 (Models list), 임베딩 (Embeddings), 그리고 (Ollama v0.13.3+ 기준) 응답 API (Responses API)가 포함됩니다. 이는 VS Code 확장 프로그램, LangChain, n8n, Hermes Agent, 그리고 CLI 도구들이 단 하나의 base_url을 변경하는 것만으로 모두 작동함을 의미합니다.

성능 튜닝 (Performance Tuning)

제한된 하드웨어에서는 몇 가지 환경 변수(environment variables)가 실질적인 차이를 만들어냅니다:

Docker Compose에서는 Ollama 서비스의 environment: 블록 아래에 이 값들을 설정합니다:

ollama:
  environment:
    - OLLAMA_KEEP_ALIVE=24h
...