나만의 프라이빗 AI 포털 구축: Open WebUI 개념 및 Docker 설치 (1/5)

📌 개요 — 로컬 AI 인터페이스의 사실상 표준

Open WebUI는 2023년 Timothy J. Baek이 오픈소스로 공개한 셀프호스팅 AI 웹 인터페이스로, 현재 GitHub 스타 90,000+를 돌파하며 로컬 AI 플랫폼의 사실상 표준(de facto standard)이 됐습니다. 단순한 채팅 UI를 넘어 RAG(문서 기반 AI), 멀티모달, 파이프라인 자동화, 멀티유저 권한 관리까지 지원하는 올인원 플랫폼입니다. ChatGPT처럼 생겼지만, 모든 데이터가 내 서버 안에서만 처리된다는 점이 결정적 차이입니다. 기업 환경에서는 사내 문서를 외부 AI에 노출하지 않고도 AI를 도입할 수 있는 사실상 유일한 현실적 선택지입니다.

🔥 왜 이렇게 많이 사용하는가?

⚡ 주요 특징 및 장점

• ✓직관적인 ChatGPT 스타일 UI — 채팅 히스토리, 폴더 정리, 북마크, 대화 공유까지 익숙한 인터페이스. 팀원 누구나 10분 내 적응 가능.
• ✓RAG (지식 기반 AI) — PDF, Word, 웹페이지를 Knowledge에 등록하면 AI가 해당 문서를 참조해 답변. 사내 문서 검색 AI 구축의 핵심.
• ✓멀티모달 지원 — 이미지 분석(Vision), 음성 입력(STT), 음성 출력(TTS). 스마트폰에서 AI와 실제 음성 통화처럼 사용 가능.
• ✓멀티유저 · 권한 관리 — 관리자/사용자 역할 분리, 회원가입 승인제, LDAP/OAuth 연동. 기업 팀 단위 운영에 필수.
• ✓Functions / Pipelines — Python으로 커스텀 툴 작성. n8n, Slack, Webhook과 연동해 업무 자동화 파이프라인 구축 가능.
• ✓Model Playground — 동일 질문에 여러 모델 답변을 나란히 비교. GPT-4o vs Claude vs Llama 성능 검증에 활용.
• ✓웹 검색 연동 — SearXNG, Brave, Google 등 검색 엔진을 연결하면 AI가 실시간 인터넷 정보를 참조해 답변.
• ✓Artifacts 지원 — 코드·HTML·SVG 생성 시 채팅창 안에서 바로 렌더링·실행. 개발자 생산성 극대화.

🆚 ChatGPT / Ollama / Dify / LM Studio와의 차이

🎯 이런 분께 추천합니다

Open WebUI 아키텍처를 이해하면 연결 오류가 생겼을 때 어디가 문제인지 즉시 파악할 수 있습니다. 실제 운영에서 문제가 생기는 지점은 대부분 Layer 3(백엔드)↔Layer 4(AI 모델) 사이의 네트워크 연결 문제입니다. OLLAMA_BASE_URL을 잘못 설정하거나 Docker 네트워크가 분리되어 있을 때 발생합니다.

🗺️ 전체 아키텍처 구성도

🔌 Ollama 연동 방식 — OLLAMA_BASE_URL 설정

Open WebUI Docker 설치 시 가장 많이 막히는 부분이 바로 OLLAMA_BASE_URL 설정입니다. Ollama와 Open WebUI가 같은 Docker Compose 네트워크에 있으면 컨테이너 이름(ollama)으로 통신합니다. 다른 네트워크·다른 서버에 Ollama가 있다면 IP를 직접 지정해야 합니다.

📚 RAG 및 벡터DB 처리 구조

🐳 Docker 기반 동작 원리 — 볼륨이 핵심

Open WebUI Docker 설치의 핵심은 볼륨(Volume) 관리입니다. 컨테이너는 언제든 삭제·재생성할 수 있지만, 볼륨에 저장된 데이터(대화 기록, 설정, 업로드 문서, 모델 파일)는 영속적으로 유지됩니다. 실제 운영에서는 볼륨을 정기적으로 외부 스토리지에 백업하는 것이 중요합니다.

Open WebUI 설치 전에 서버 사양과 필수 소프트웨어를 확인하지 않으면 설치 후 GPU 인식 실패, 포트 충돌, Docker 권한 오류 등 흔한 문제에 부딪히게 됩니다. 특히 GPU 서버라면 NVIDIA Driver 버전과 CUDA, Container Toolkit의 버전 매핑을 미리 확인하는 것이 중요합니다.

💻 시스템 사양

🖥️ 운영체제별 지원 현황

📦 Docker 설치 (Ubuntu / Debian 기준)

Open WebUI Docker 설치는 공식 Docker 스크립트를 사용하는 것이 가장 안정적입니다. 패키지 관리자(apt)로 설치하면 구버전이 설치될 수 있으므로 공식 스크립트를 권장합니다.

# 기존 구버전 Docker 제거 (있다면)
sudo apt remove docker docker-engine docker.io containerd runc 2>/dev/null
 
# 공식 Docker 설치 스크립트 (가장 안전하고 최신 버전 설치)
curl -fsSL https://get.docker.com | sudo sh
 
# 현재 사용자를 docker 그룹에 추가 — 재로그인 필요
sudo usermod -aG docker $USER
newgrp docker
 
# 설치 확인
docker --version          # Docker 버전 출력되면 정상
docker compose version    # Compose v2 출력 확인
docker ps                 # sudo 없이 실행되면 그룹 설정 완료

⚡ NVIDIA Container Toolkit 설치 (GPU 사용 시만)

# 드라이버 먼저 확인 — 출력되면 드라이버 정상
nvidia-smi
 
# NVIDIA Container Toolkit 저장소 추가
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 \
  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
  | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
 
# 설치 및 Docker 연동
sudo apt update && sudo apt install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
 
# GPU 인식 확인 — nvidia-smi 출력되면 성공
docker run --rm --gpus all nvidia/cuda:12.0-base-ubuntu22.04 nvidia-smi

✅ 설치 전 최종 체크리스트

• ✓Docker v24 이상 + Docker Compose v2 설치 완료
• ✓docker ps sudo 없이 실행 가능 (docker 그룹 적용 확인)
• iGPU 사용 시 — docker run --gpus all nvidia/cuda:... nvidia-smi 정상 출력 확인
• i포트 3000 방화벽에서 허용 (sudo ufw allow 3000 또는 보안 그룹 설정)
• !외부 공개 서버라면 Cloudflare Tunnel 또는 Nginx + Let’s Encrypt HTTPS 준비 필수

Open WebUI Docker 설치는 현재 가장 많이 사용하는 구축 방식입니다. Docker를 사용하면 OS 환경에 관계없이 동일한 방법으로 설치할 수 있고, 업데이트·백업·서버 이전도 Docker 명령어 몇 줄로 해결됩니다. 아래 4가지 방법 중 본인 환경에 맞는 것을 선택하세요.

🚀 방법 1 — 단일 컨테이너 (외부 API 전용)

Ollama 없이 OpenAI, Claude, Groq 같은 외부 API만 사용할 계획이라면 가장 간단한 단일 컨테이너로 시작하세요. 서버 사양이 낮아도 부담 없이 운영 가능합니다.

docker run -d \
  --name open-webui \
  -p 3000:8080 \
  -v open-webui:/app/backend/data \
  --restart unless-stopped \
  ghcr.io/open-webui/open-webui:main

🐳 방법 2 — Docker Compose + Ollama (로컬 모델 추천)

Open WebUI + Ollama를 함께 구성하는 가장 많이 사용하는 방법입니다. Docker Compose를 사용하면 두 서비스가 자동으로 같은 네트워크에 묶여 OLLAMA_BASE_URL을 http://ollama:11434로 설정하면 바로 통신됩니다.

services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    volumes:
      - ollama:/root/.ollama
    ports:
      - "11434:11434"
    restart: unless-stopped
 
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    depends_on:
      - ollama
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434
    volumes:
      - open-webui:/app/backend/data
    ports:
      - "3000:8080"
    restart: unless-stopped
 
volumes:
  ollama:
  open-webui:

# 폴더 생성 및 이동
mkdir -p ~/open-webui && cd ~/open-webui
 
# docker-compose.yml 저장 후 백그라운드 실행
docker compose up -d
 
# 컨테이너 상태 확인 (Up 상태여야 정상)
docker compose ps
 
# Open WebUI 로그 실시간 확인
docker compose logs -f open-webui

⚡ 방법 3 — Docker Compose + Ollama + NVIDIA GPU

Open WebUI GPU 설정은 Ollama 서비스에 deploy.resources.reservations 블록만 추가하면 됩니다. NVIDIA Container Toolkit이 미리 설치되어 있어야 합니다. GPU가 정상 인식되면 Ollama 로그에 gpu memory available 메시지가 출력됩니다.

  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    volumes:
      - ollama:/root/.ollama
    ports:
      - "11434:11434"
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all          # 모든 GPU 사용 (특정 1개만: count: 1)
              capabilities: [gpu]
    restart: unless-stopped

🌐 방법 4 — Cloudflare Tunnel로 외부 HTTPS 공개

Open WebUI Cloudflare Tunnel 연동은 공인 IP나 포트 포워딩 없이 도메인 기반 HTTPS를 구성할 수 있는 가장 쉬운 방법입니다. 홈랩, 공유기 뒤 서버, 사설 IP 환경에서 특히 유용합니다.

# 1. cloudflared 설치 (Ubuntu/Debian)
curl -L --output cloudflared.deb \
  https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared.deb
 
# 2. Cloudflare 계정 로그인
cloudflared tunnel login
 
# 3. 터널 생성
cloudflared tunnel create open-webui
 
# 4. Cloudflare 대시보드에서 설정
#    Zero Trust → Networks → Tunnels → 생성한 터널 선택
#    Public Hostname 추가:
#    Subdomain: ai, Domain: yourdomain.com
#    Service: http://localhost:3000
 
# 5. 서비스로 등록 (서버 재부팅 시 자동 실행)
sudo cloudflared service install
sudo systemctl start cloudflared