Docker Compose로 Open Web UI 구성하기 – 5분 만에 나만의 ChatGPT 웹 인터페이스 만들기

Open Web UI, 로컬에서 ChatGPT처럼 쓰는 방법

로컬 LLM을 설치했지만 명령줄에서만 사용하기 불편하신가요? Open Web UI를 사용하면 ChatGPT와 똑같은 웹 인터페이스에서 Ollama, OpenAI API 등 다양한 AI 모델을 사용할 수 있습니다. 이 글에서는 Docker Compose를 활용해 단 5분 만에 Open Web UI를 구성하는 방법을 알려드립니다.

Open Web UI란 무엇인가요?

Open Web UI는 Ollama, OpenAI, Claude API 등 다양한 LLM을 웹 브라우저에서 편하게 사용할 수 있게 해주는 오픈소스 인터페이스입니다. ChatGPT의 웹 인터페이스와 비슷한 UI를 제공하면서도 완전히 무료로 사용할 수 있어 개발자들 사이에서 인기가 높습니다.

주요 특징으로는 채팅 기록 자동 저장, 다중 모델 지원, 커스텀 프롬프트 관리, 파일 업로드 기능 등이 있어 실무에서도 충분히 활용 가능합니다.

사전 준비사항

Docker Compose를 이용한 설치를 진행하기 전에 다음 요소들이 준비되어 있어야 합니다.

먼저 Docker와 Docker Compose가 설치되어 있어야 합니다. Windows나 Mac을 사용하신다면 Docker Desktop을 설치하면 Docker Compose가 함께 설치됩니다. Linux 사용자는 Docker Engine과 Docker Compose를 각각 설치해야 합니다.

Ollama를 로컬에서 사용하려면 Ollama도 미리 설치해두세요. Ollama 공식 웹사이트에서 운영체제에 맞는 설치 파일을 다운로드할 수 있습니다.

Docker Compose 파일 작성하기

프로젝트 폴더를 만들고 그 안에 docker-compose.yml 파일을 생성합니다. 가장 기본적인 설정부터 시작해보겠습니다.

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

volumes:
  open-webui:

이 설정의 의미를 하나씩 살펴보겠습니다. image는 사용할 Docker 이미지를 지정하는데, Open Web UI의 최신 버전을 가져옵니다. ports는 포트 매핑 설정으로, 로컬의 3000번 포트로 접속하면 컨테이너 내부의 8080번 포트로 연결됩니다.

volumes는 데이터 영속성을 위한 설정입니다. 채팅 기록이나 설정이 여기에 저장되므로 컨테이너를 재시작해도 데이터가 유지됩니다. environment의 OLLAMA_BASE_URL은 Ollama 서버 주소를 지정합니다. host.docker.internal은 Docker 컨테이너에서 호스트 머신에 접근할 때 사용하는 특수 DNS 이름입니다.

Open Web UI 실행하기

터미널에서 docker-compose.yml 파일이 있는 디렉토리로 이동한 후 다음 명령어를 실행합니다.

docker-compose up -d

-d 옵션은 백그라운드에서 실행하라는 의미입니다. 처음 실행할 때는 이미지를 다운로드하는 시간이 필요하므로 1~2분 정도 기다려주세요.

실행이 완료되면 웹 브라우저에서 http://localhost:3000 으로 접속합니다. 처음 접속하면 회원가입 화면이 나타나는데, 로컬 환경이므로 원하는 이메일과 비밀번호로 계정을 만들면 됩니다. 이 계정 정보는 외부로 전송되지 않고 로컬 데이터베이스에만 저장됩니다.

Ollama 모델과 연동하기

Open Web UI에 로그인한 후 왼쪽 상단의 모델 선택 드롭다운을 클릭하면 Ollama에 설치된 모델들이 자동으로 표시됩니다. 만약 모델이 보이지 않는다면 Ollama가 제대로 실행 중인지 확인해보세요.

Ollama에 모델을 추가하려면 터미널에서 다음과 같은 명령어를 실행하면 됩니다.

ollama pull llama3

모델 다운로드가 완료되면 Open Web UI를 새로고침하면 새 모델이 목록에 나타납니다.

OpenAI API 연동하기

OpenAI나 Claude API를 사용하려면 환경변수를 추가해야 합니다. docker-compose.yml 파일의 environment 섹션에 다음 내용을 추가하세요.

environment:
  - OLLAMA_BASE_URL=http://host.docker.internal:11434
  - OPENAI_API_KEY=your-api-key-here
  - ENABLE_OPENAI_API=true

API 키는 OpenAI 웹사이트에서 발급받을 수 있습니다. 설정을 변경한 후에는 다음 명령어로 컨테이너를 재시작해야 변경사항이 적용됩니다.

docker-compose restart

주요 설정 옵션 알아보기

Open Web UI는 다양한 환경변수로 커스터마이징이 가능합니다. 데이터 저장 경로를 변경하고 싶다면 volumes를 수정할 수 있고, 포트 번호를 바꾸고 싶다면 ports의 왼쪽 숫자를 원하는 포트로 변경하면 됩니다.

회원가입을 비활성화하고 싶다면 WEBUI_AUTH=False 환경변수를 추가할 수 있습니다. 이렇게 하면 로그인 없이 바로 사용할 수 있지만, 공용 네트워크에서는 보안상 권장하지 않습니다.

자주 발생하는 문제 해결

Ollama 모델이 보이지 않는 경우 대부분 네트워크 설정 문제입니다. OLLAMA_BASE_URL이 올바른지 확인하고, Ollama가 11434 포트에서 실행 중인지 체크해보세요. Linux 환경에서는 host.docker.internal 대신 172.17.0.1 같은 실제 IP를 사용해야 할 수도 있습니다.

포트 충돌이 발생하면 3000번 포트가 이미 사용 중일 수 있습니다. docker-compose.yml의 포트를 3001:8080 같은 다른 번호로 변경해보세요.

컨테이너 로그는 다음 명령어로 확인할 수 있어 문제 진단에 도움이 됩니다.

docker-compose logs -f

마무리하며

Docker Compose로 Open Web UI를 구성하면 복잡한 설정 없이 몇 줄의 코드만으로 강력한 AI 인터페이스를 구축할 수 있습니다. 로컬 LLM을 더 편하게 활용하고 싶거나, 여러 AI 모델을 하나의 인터페이스에서 관리하고 싶다면 지금 바로 시도해보세요.

설정 파일은 Git으로 관리하면 팀원들과 쉽게 공유할 수 있고, 서버 환경에도 동일하게 배포할 수 있어 실무에서도 유용하게 활용할 수 있습니다.