Docker를 이용한 Open WebUI 구축: Ollama 연동 및 데이터 관리 가이드

Open WebUI를 Docker 환경에서 배포할 때 가장 빈번하게 발생하는 세 가지 이슈는 이미지 다운로드 속도, 호스트의 Ollama 서비스 연동, 그리고 컨테이너 재시작 시의 데이터 보존입니다. 이 글에서는 효율적인 배포 프로세스와 설정 최적화 방법을 설명합니다.

1. 최적의 이미지 선택 및 다운로드

Open WebUI 공식 이미지는 GitHub Container Registry(GHCR)를 기반으로 합니다. 네트워크 환경에 따라 GHCR 접속이 원활하지 않을 경우 Docker Hub의 미러 이미지를 활용하는 것이 효율적입니다.

# GHCR 공식 이미지 다운로드 시도
docker pull ghcr.io/open-webui/open-webui:main

# 네트워크 지연 시 대체 경로(미러) 사용 예시
docker pull ghcr.1ms.run/open-webui/open-webui:main

2. 핵심 배포 커맨드 및 옵션 분석

컨테이너를 처음 실행할 때 데이터 영속성과 포트 포워딩을 올바르게 설정해야 합니다. 아래는 가장 표준적인 실행 명령입니다.

docker run -d \
  -p 3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -v owui_data:/app/backend/data \
  --name ai-web-interface \
  --restart always \
  ghcr.io/open-webui/open-webui:main

주요 파라미터 상세 설명

옵션	설명
`-p 3000:8080`	호스트의 3000번 포트를 컨테이너 내부 8080 포트와 연결합니다.
`--add-host`	Linux 환경에서 컨테이너가 호스트 머신의 서비스(Ollama 등)에 접근할 수 있도록 게이트웨이를 설정합니다.
`-v owui_data:...`	Docker 볼륨을 생성하여 대화 기록 및 설정 데이터를 컨테이너 외부로 격리 저장합니다.
`--restart always`	시스템 재부팅이나 오류 발생 시 컨테이너가 자동으로 다시 실행되도록 보장합니다.

3. 호스트 Ollama 서비스 연결 설정

기본적으로 컨테이너 내부의 127.0.0.1은 호스트가 아닌 컨테이너 자신을 가리킵니다. 따라서 호스트에서 실행 중인 Ollama(포트 11434)에 접속하려면 환경 변수 설정이 필수적입니다.

# 환경 변수를 포함한 실행 예시
docker run -d \
  -p 3000:8080 \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  -v owui_data:/app/backend/data \
  --add-host=host.docker.internal:host-gateway \
  --name ai-web-interface \
  ghcr.io/open-webui/open-webui:main

배포 후에는 컨테이너 내부에서 아래 명령어로 호스트 통신 여부를 확인할 수 있습니다.

docker exec -it ai-web-interface curl http://host.docker.internal:11434/api/tags

4. Docker Compose를 이용한 관리 자동화

설정 정보가 많아질 경우 관리 편의성을 위해 docker-compose.yml 파일을 사용하는 것이 좋습니다.

version: '3.8'
services:
  webui-app:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui-service
    ports:
      - "3000:8080"
    environment:
      - 'OLLAMA_BASE_URL=http://host.docker.internal:11434'
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - storage_volume:/app/backend/data
    restart: unless-stopped

volumes:
  storage_volume:

5. 트러블슈팅 체크리스트

이미지 풀링 실패: 프록시 설정 혹은 미러 사이트 활용 여부를 점검하십시오.
모델 목록 미출력: OLLAMA_BASE_URL이 정확한지, 호스트의 Ollama가 외부 접속을 허용하고 있는지(OLLAMA_HOST=0.0.0.0 설정 확인) 점검하십시오.
데이터 초기화 이슈: docker volume ls 명령어를 통해 볼륨이 정상적으로 생성되었는지 확인하십시오.
네트워크 보안: 클라우드 서버 환경이라면 방화벽(Security Group)에서 3000번 포트가 허용되어 있는지 체크해야 합니다.

태그: docker Open WebUI Ollama self-hosting LLM

8월 11일 16:15에 게시됨

괴물 클럽