Docker와 Open WebUI를 사용하여 Ubuntu에서 GPU로 Ollama 실행하기

대규모 언어 모델(LLM)을 로컬에서 실행하면 개발자가 AI 환경에 대해 더 많은 제어권을 가질 수 있습니다. Ollama, Docker, 그리고 Open WebUI를 사용하면 Ubuntu 서버의 NVIDIA GPU 가속 기능을 활용하여 자체 호스팅형 AI 챗봇을 구축할 수 있습니다.

본 가이드에서는 GPU 기반 로컬 AI를 시작하는 데 필요한 필수 구성 요소를 다룹니다.

준비물

Ollama를 배포하기 전에 다음 항목들을 준비하세요:

Ubuntu 22.04 또는 24.04 LTS
호환 가능한 NVIDIA GPU
NVIDIA 드라이버
Docker Engine
NVIDIA Container Toolkit
선택한 모델에 충분한 GPU VRAM, RAM 및 저장 공간

1단계: 서버 업데이트 및 GPU 확인

SSH를 통해 로그인하여 시스템을 업데이트합니다:

sudo apt update && sudo apt upgrade -y

Ubuntu가 GPU를 인식하는지 확인합니다:

lspci | grep -i nvidia

GPU 모델이 포함된 줄이 보여야 합니다. 아무것도 나타나지 않으면 GPU가 감지되지 않은 것이므로, 계속하기 전에 호스팅 제공업체에 문의하세요.

2단계: NVIDIA 드라이버 설치

GPU에 대한 권장 드라이버 목록을 확인합니다:

sudo ubuntu-drivers devices

자동으로 설치합니다 (이것은 권장 버전을 선택합니다):

sudo ubuntu-drivers autoinstall

재부팅합니다:

sudo reboot

다시 연결한 후, 다음 명령어로 확인합니다:

nvidia-smi

GPU 이름, 드라이버 버전 및 VRAM이 표시되는 표가 보여야 합니다. 이것이 보인다면 드라이버가 정상적으로 작동하는 것입니다.

⚠️ 보안 부팅(Secure Boot) 경고 BIOS에서 Secure Boot이 활성화된 경우, NVIDIA 커널 모듈이 로드되는 것을 거부할 수 있으며 nvidia-smi가 실패합니다. 이 경우 BIOS/IPMI에서 Secure Boot을 비활성화하거나 설치 프로그램이 요청할 때 MOK 키를 등록하세요. 문제 해결(Troubleshooting), 문제 1을 참조하세요.

3단계: Docker 설치

curl -fsSL https://get.docker.com | sudo sh

사용자가 sudo 없이 Docker를 실행할 수 있도록 권한을 부여합니다:

sudo usermod -aG docker $USER

로그아웃했다가 다시 로그인하거나 (newgrp docker 실행), 다음 명령어로 테스트합니다:

docker run --rm hello-world

4단계: NVIDIA Container Toolkit 설치

이 부분은 Docker 컨테이너가 GPU를 사용할 수 있게 해줍니다.
NVIDIA의 레지스트리를 추가하세요:

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
...

설치하세요:

sudo apt update
sudo apt install -y nvidia-container-toolkit

Docker에게 NVIDIA 런타임을 사용하도록 알려주고, Docker를 재시작하세요:

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

컨테이너 내부에서 GPU 접근 테스트

docker run --rm --gpus all ubuntu nvidia-smi

만약 2단계와 동일한 GPU 표가 보인다면, Docker로의 GPU 패스스루(GPU passthrough)가 작동하는 것입니다. 이 테스트가 통과하기 전까지는 진행하지 마세요.

5단계: 프로젝트 폴더 생성

mkdir -p ~/ai-server && cd ~/ai-server

5.1 docker-compose.yml 파일 생성

nano docker-compose.yml

여기에 붙여넣으세요:
services:
  ollama:
...

Ctrl+O, Enter를 누른 후 Ctrl+X로 저장하세요.

5.2 .env 파일 생성

임의의 비밀 키(secret key)를 생성하세요:

echo "WEBUI_SECRET_KEY=$(openssl rand -hex 32)" > .env
echo "ENABLE_SIGNUP=true" >> .env

5.3 Caddyfile 생성

옵션 A: 도메인을 사용할 경우 (권장, 무료 자동 HTTPS). 먼저 도메인의 DNS A 레코드를 서버 IP로 지정한 다음:

cat > Caddyfile << 'EOF'
ai.yourdomain.com {
    reverse_proxy open-webui:8080
...

ai.yourdomain.com을 실제 도메인으로 교체하세요.

옵션 B: 도메인이 없는 경우 (테스트용, 일반 HTTP).

cat > Caddyfile << 'EOF'
:80 {
    reverse_proxy open-webui:8080
...

6단계: 방화벽 열기

SSH, HTTP, HTTPS만 필요합니다:

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
...

⭐ 중요: Docker는 ports:로 게시하는 모든 포트에 대해 UFW를 우회할 수 있습니다. 이것이 위 compose 파일에 Ollama가 게시된 포트가 없는 이유입니다. 절대로 11434 포트를 인터넷에 공개하지 마세요.

7단계: 모든 서비스 시작하기

docker compose up -d

세 개의 컨테이너가 모두 실행 중인지 확인합니다:

docker compose ps

8단계: 첫 번째 모델 다운로드하기

docker exec -it ollama ollama pull llama3.1:8b

명령줄에서 테스트해봅니다:

docker exec -it ollama ollama run llama3.1:8b "Explain what a dedicated server is in two sentences."

모델이 GPU를 사용하는지 확인하기 (가장 중요한 점)

모델을 로드하는 동안 다음 명령어를 실행합니다:

docker exec -it ollama ollama ps

PROCESSOR 항목을 확인하세요:

100% GPU: 완벽합니다. 모델 전체가 VRAM에 있습니다.
40%/60%: 모델이 VRAM보다 크므로 일부는 CPU에서 실행됩니다 (느림). 더 작은 모델을 사용하거나 양자화(quantization) 수준을 낮추세요.
CPU/GPU: 모델이 VRAM보다 크므로 일부는 CPU에서 실행됩니다 (느림). 더 작은 모델을 사용하거나 양자화 수준을 낮추세요.
100% CPU: GPU가 사용되지 않고 있습니다. 문제 해결(Troubleshooting)의 Problem 3을 참고하세요.

두 번째 터미널에서 실시간으로 GPU 사용량을 확인할 수도 있습니다:

watch -n 1 nvidia-smi

9단계: 채팅 인터페이스 열고 관리자 계정 만들기

https://ai.yourdomain.com (또는 옵션 B의 경우 http://YOUR_SERVER_IP)로 접속합니다.

Get Started를 클릭합니다.
계정을 만듭니다. 첫 번째 계정이 관리자가 됩니다.
상단 드롭다운에서 모델을 선택하고 채팅을 시작합니다.

가입 기능 잠그기 (관리자 생성 직후 수행)

이 작업을 하지 않으면 URL을 아는 누구라도 가입할 수 있습니다.

sed -i 's/ENABLE_SIGNUP=true/ENABLE_SIGNUP=false/' .env
docker compose up -d

⚠️ 참고: 일부 Open WebUI 버전에서는 가입 설정이 첫 시작 후 관리자 패널에도 저장됩니다. 만약 여전히 가입이 열려 있다면, Admin Panel → Settings → General로 이동하여 Enable New Sign Ups를 비활성화하세요.

어떤 모델을 실행해야 할까요? (VRAM 가이드)

4비트 양자화(quantized) 모델(Ollama의 기본값)에 대한 일반적인 규칙은 다음과 같습니다: GB 단위의 모델 크기는 필요한 VRAM과 컨텍스트를 위한 1~2GB가 추가됩니다.

사용자의 GPU VRAM: 6~8 GB
편안하게 사용할 수 있는 모델 크기: 3B ~ 8B
예시 사용처: 채팅, 요약, 간단한 코딩 도움

GPU VRAM 용량별 권장 모델 및 사용 사례

GPU VRAM: 1216 GB
권장 모델 크기: 8B14B
예시 활용: 향상된 추론 능력, 코딩 지원

GPU VRAM: 24 GB
권장 모델 크기: 최대 ~30B
예시 활용: 강력한 범용 어시스턴트

GPU VRAM: 48 GB
권장 모델 크기: 최대 ~70B
예시 활용: 최고 수준의 오픈 소스 모델에 근접

GPU VRAM: 80 GB 이상
권장 모델 크기: 긴 컨텍스트를 가진 70B+
예시 활용: 대규모 또는 다중 사용자 워크로드

ollama.com/library에서 사용 가능한 모델을 찾아 다음 명령어로 다운로드할 수 있습니다:

docker exec -it ollama ollama pull MODEL_NAME:TAG

설치된 모델 목록을 확인하고 더 이상 필요 없는 모델은 삭제하세요:

docker exec -it ollama ollama list
docker exec -it ollama ollama rm MODEL_NAME:TAG

자체 애플리케이션에서 API 사용하기

Ollama는 OpenAI와 호환됩니다. 포트를 공개하지 않았기 때문에, Docker 네트워크 내부에서 호출하거나 서버 자체에서 임시로 테스트해야 합니다:

docker exec -it ollama curl http://localhost:11434/v1/chat/completions \
  -H

### 문제 2 — `docker: Error response from daemon: could not select device driver "" with capabilities: [[gpu]]`

NVIDIA Container Toolkit이 누락되었거나 Docker가 구성되지 않았습니다. 다음 명령을 다시 실행하세요:

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


그런 다음 재테스트합니다: `docker run --rm --gpus all ubuntu nvidia-smi`

### 문제 3 — Ollama가 GPU가 아닌 CPU에서 실행됨 ("Ollama not using GPU")

다음 체크리스트를 순서대로 확인하세요:

-   호스트(host)에서 `nvidia-smi`가 작동하는지? 그렇지 않다면, 문제 1로 이동합니다.
-   `docker run --rm --gpus all ubuntu nvidia-smi`가 작동하는지? 그렇지 않다면, 문제 2로 이동합니다.
-   compose 파일에 ollama 서비스의 `deploy.resources.reservations.devices` 블록이 포함되어 있습니까? 이것 없이는 컨테이너가 GPU를 사용할 수 없습니다.
-   Ollama 로그에서 GPU 감지 메시지를 확인하세요:

docker logs ollama 2>&1 | grep -i -E "gpu|cuda|vram"

-   모델 자체가 VRAM에 너무 큰 것은 아닌가요? `ollama ps`를 실행해 보세요. 예를 들어, CPU/GPU 비율이 30%/70%라는 것은 오버플로우(overflowing) 상태임을 의미합니다. 더 작은 모델을 사용하세요.

### 문제 4 — 처음에는 GPU로 작동하지만 시간이 지나면 Ollama가 CPU로 폴백됨 (fallback)

이는 일부 Linux 설정에서 GPU 드라이버 상태가 손실되는 경우에 발생하는 알려진 문제입니다. UVM 모듈을 다시 로드하고 컨테이너를 재시작해 보세요:

sudo rmmod nvidia_uvm && sudo modprobe nvidia_uvm
docker restart ollama


계속해서 이런 현상이 발생한다면, 최신 드라이버 버전을 사용하고 시스템을 업데이트 상태로 유지하는지 확인하세요.

### 문제 5 — Open WebUI에 모델이 표시되지 않거나 "Ollama connection error"가 나타남

-   `OLLAMA_BASE_URL=http://ollama:11434`가 설정되었는지, 그리고 두 컨테이너가 동일한 compose 프로젝트 내에 있는지 확인하세요.
-   Ollama가 실행 중인지 확인합니다: `docker compose ps` 및 `docker logs ollama`를 사용하세요.
-   실제로 모델을 풀(pull)했는지 확인합니다: `docker exec -it ollama ollama list`를 사용하세요.
-   재시작: `docker compose restart open-webui`

### 문제 6 — HTTPS가 작동하지 않거나 Caddy에서 인증서 오류가 표시됨

-   Caddy를 시작하기 전에 DNS A 레코드가 서버 IP를 가리키는지 확인해야 합니다. `dig +short ai.yourdomain.com`으로 확인하세요.
-   포트 80과 443은 UFW와 모든 제공업체 수준 방화벽에서 열려 있어야 합니다.
-   로그 읽기: `docker logs caddy`
-   반복적인 실패 시도로 인해 인증서 속도 제한에 걸린 경우, 기다렸다가 다시 시도하거나 옵션 B를 먼저 테스트하세요.

### 문제 7 - "CUDA out of memory" 또는 모델 로드 실패

-   더 작은 모델이나 더 낮은 양자화(quantization)를 사용하세요.
-   Open WebUI에서 컨텍스트 길이(Context Length)를 줄이세요 (Settings → Advanced Params → Context Length).
-   다른 프로세스가 VRAM을 점유하고 있지 않은지 확인하세요: `nvidia-smi`는 GPU를 사용하는 프로세스를 보여줍니다.

### 문제 8 - 응답 속도가 매우 느림

`ollama ps`를 실행해 보세요. 만약 100% GPU가 아니라면, 그것이 원인입니다.

-   큰 컨텍스트 창은 속도를 늦춥니다. 컨텍스트 길이를 낮추세요.
-   유휴 상태 이후의 첫 요청이 더 느린 이유는 모델이 VRAM에 로드되기 때문입니다. `OLLAMA_KEEP_ALIVE=30m` (이미 설정됨)는 이를 줄여줍니다.

### 문제 9 - 포트 3000 또는 11434가 인터넷에서 접근 가능함

이러한 포트를 공개해서는 안 됩니다. `ollama`와 `open-webui`에 대한 모든 포트 항목을 제거한 다음, `docker compose up -d`를 실행하세요. Docker는 공개된 포트에 대해 UFW를 우회한다는 점을 기억하세요.

## 유지보수(Maintenance)

최신 버전으로 업데이트하기:

cd ~/ai-server
docker compose pull
docker compose up -d
...


**데이터 백업 (채팅, 사용자, 설정):**

docker run --rm -v ai-server_open_webui_data:/data -v $(pwd):/backup ubuntu
tar czf /backup/open-webui-backup.tar.gz /data


(볼륨 이름은 폴더 이름에 `_open_webui_data`를 붙인 것입니다. `docker volume ls`로 확인하세요.)

**유용한 일일 명령어:**

**실행 중인 컨테이너 보기**: `docker compose ps`
**로그 보기**: `docker compose logs -f`
**로드된 모델**: `docker exec -it ollama ollama ps`
**모두 중지**: `docker compose down`
**모두 시작**: `docker compose up -d`
**GPU 사용량**: `nvidia-smi`

## 보안 체크리스트

- SSH 키 로그인만 허용 (비밀번호 로그인 비활성화)
- Ollama 포트가 공개되지 않음
- 관리자 생성 후 회원가입 기능 비활성화
- Caddy를 통해 HTTPS 활성화
- WEBUI_SECRET_KEY는 임의 값으로 설정됨
- 방화벽은 22, 80, 443 포트만 허용함
- 정기적인 업데이트 및 백업이 예약되어 있음