OpenWebUI 셋업 방법

2025-08-12

endpoint 주소들을 이미 알고 있을 때 개인용 openwebui 셋업 하는 법 알려줘

좋아요. “엔드포인트 주소는 이미 알고 있다”는 전제로, 빠르게 개인용 Open WebUI 를 띄우고 각종(OpenAI·Ollama·vLLM·OpenRouter 등) 커스텀 엔드포인트를 붙이는 최소 셋업 을 step‑by‑step으로 정리해드릴게요.

1) 설치 방식 고르기 (Docker 추천)

가장 간단한 건 Docker입니다. Open WebUI 공식 퀵스타트도 Docker를 권장해요. Open WebUI

A. Docker Compose (권장)

프로젝트 폴더에서 아래 파일을 저장하세요: docker-compose.yml

services:
  openwebui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: openwebui
    ports:
      - "3000:8080"          # 브라우저 접속은 http://localhost:3000
    volumes:
      - ./openwebui-data:/app/backend/data   # 채팅/설정 영속화
    environment:
      # 필요 시 기본값만으로 시작하고, 이후 UI에서 세팅하는 것을 권장
      # 최초 실행 후 일부 항목은 'PersistentConfig'로 내부에 저장됩니다.
      # (아래 5) 참고)
      WEBUI_URL: "http://localhost:3000"
    restart: unless-stopped

실행:

docker compose up -d

B. 단일 명령으로 실행(docker run)

docker run -d --name openwebui \
  -p 3000:8080 \
  -v $(pwd)/openwebui-data:/app/backend/data \
  ghcr.io/open-webui/open-webui:main

공식 퀵스타트의 기본 흐름과 동일합니다. Open WebUI

2) 최초 접속

브라우저에서 http://localhost:3000으로 들어가세요. 이후 계정/관리자 생성 절차는 기본 UI 흐름을 따릅니다(로그인/회원가입 토글 등은 환경변수로 제어 가능). 관련 일반/보안 변수는 “Environment Variable Configuration” 문서에 정리돼 있습니다. Open WebUI

3) 모델 제공자(Provider) 추가 → “엔드포인트 붙이기”

Open WebUI는 여러 개의 OpenAI‑호환/로컬 엔진 엔드포인트를 동시에 등록 할 수 있습니다.

A. OpenAI‑호환(예: OpenAI, OpenRouter, vLLM, LM Studio 등)

Settings → Models → Providers 로 이동
OpenAI Compatible 유형 추가
Base URL(이미 알고 계신 엔드포인트)과 API Key 입력 → 저장
공식 “Starting With OpenAI” 가이드가 이 경로를 정확히 안내합니다. Open WebUI

팁: vLLM/LM Studio처럼 OpenAI‑호환 서버는 보통 http(s)://HOST:PORT/v1 형태의 Base URL을 씁니다. 모델 이름은 해당 서버에서 노출되는 이름 그대로 적어야 목록에 뜹니다(모델 리스트 캐시 TTL도 조정 가능). Open WebUI

B. Ollama(로컬) 사용 시

방법 2가지 중 편한 쪽으로:

UI에서 Provider로 “Ollama” 추가 후 Base URL(예: http://<서버IP>:11434) 지정
환경변수로 미리 넘기기: OLLAMA_BASE_URL=http://<서버IP>:11434
공식 Ollama 연동 가이드 참조. Open WebUI

주의: Docker로 분리 배치했다면 127.0.0.1 대신 컨테이너에서 접근 가능한 주소(예: 브리지 네트워크의 서비스명 또는 호스트 IP)를 써야 합니다. 모델 리스트 타임아웃/캐시는 AIOHTTP_CLIENT_TIMEOUT_*, MODELS_CACHE_TTL로 조절 가능합니다. Open WebUI

4) (선택) 인증/싱글유저/도메인 설정

WEBUI_URL : OAuth/SSO 등을 쓸 계획이면 도메인으로 미리 지정하세요(중요). Open WebUI
회원가입/로그인 폼 표시, 기본 역할 등은 ENABLE_SIGNUP, ENABLE_LOGIN_FORM, DEFAULT_USER_ROLE 등으로 제어합니다. Open WebUI

5) 환경변수와 “PersistentConfig” 동작 이해(중요)

Open WebUI는 최초 기동 시점 에 일부 설정(‘PersistentConfig’ 표시된 항목)을 내부 DB에 영구 저장 합니다. 그 뒤에는 같은 환경변수를 바꿔도 내부 저장값이 우선됩니다. 필요하면 ENABLE_PERSISTENT_CONFIG=False로 비활성화하거나, 관리자 UI에서 값을 변경 하세요. Open WebUI

6) (선택) 외부 노출/HTTPS (Traefik 예시)

여러 서비스와 함께 쓰거나 Let’s Encrypt로 자동 HTTPS를 원하면 Traefik을 리버스 프록시로 두면 편합니다. Compose 예제와 기본 구성 흐름은 Traefik 문서에 잘 정리돼 있어요. doc.traefik.io+1

7) 업데이트/백업

데이터 경로 : ./openwebui-data 볼륨에 채팅/설정이 저장됩니다(Compose 예제 기준).
업데이트는 이미지 재풀/재시작으로 충분합니다. 설정 항목 대부분은 위 PersistentConfig 규칙 을 따릅니다. Open WebUI

자주 막히는 포인트(짧게)

모델이 안 보임 : Base URL/키가 맞는지, 컨테이너 간 네트워크 경로가 맞는지 확인. 모델리스트 캐시/타임아웃 조정. Open WebUI
로컬 Ollama 연결 : Docker 분리 배치 시 localhost 대신 호스트 IP 또는 도커 네트워크의 서비스명 사용. Open WebUI

필요하시면 현재 가지고 계신 엔드포인트(Base URL/키/모델명) 조합 에 맞춰 docker-compose.yml을 바로 맞춤 생성해 드릴게요.

pip 설치 방식으로 가이드해줘

좋습니다. pip 기반으로 Open WebUI를 설치하고, 이미 알고 계신 엔드포인트를 붙이는 방법을 단계별로 정리해드릴게요.

1) Python 환경 준비

Python 3.10 이상 이 필요합니다. (venv 권장)

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip

2) Open WebUI 설치

공식 저장소에서 PyPI 배포 버전을 설치합니다.

pip install open-webui

설치 후, CLI 명령어 open-webui가 등록됩니다.

3) 실행

open-webui serve

기본적으로 http://127.0.0.1:8080에서 실행됩니다.
원한다면 포트 변경:

open-webui serve --port 3000

4) 최초 접속 & 관리자 계정 생성

브라우저에서 http://localhost:3000 → 첫 로그인 시 관리자 계정을 만듭니다.

5) 엔드포인트 등록 (OpenAI 호환 / Ollama 등)

A. UI에서 설정

Settings → Models → Providers
Add Provider → "OpenAI Compatible" 선택
Base URL : 알고 계신 엔드포인트 주소 입력
API Key : 해당 서비스의 키 입력
저장 후 모델 목록을 불러와 선택

vLLM/LM Studio의 경우 Base URL이 http://HOST:PORT/v1 형식인 경우가 많습니다.

B. 환경변수로 미리 세팅 (선택)

실행 전에 아래 예시처럼 환경변수를 설정하면 UI에서 자동으로 반영됩니다.

export OPENAI_API_BASE_URL="https://your-endpoint.example.com/v1"
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"
open-webui serve

Ollama 사용 시:

export OLLAMA_BASE_URL="http://localhost:11434"

6) 데이터 영속화

pip 실행은 기본적으로 현재 디렉터리의 .open-webui 폴더에 데이터(채팅 기록, 설정)를 저장합니다.

다른 위치에 저장하려면:

open-webui serve --data-dir /path/to/data

7) (선택) HTTPS & 외부 접근

로컬에서만 쓰는 경우 무관하지만, 외부 접근 시 리버스 프록시(Nginx/Traefik) + HTTPS 적용을 권장합니다.
도메인 기반 접근 시 WEBUI_URL 환경변수를 세팅하면 OAuth/SSO 연동 시 편합니다.

export WEBUI_URL="https://chat.example.com"

8) 업데이트

pip install --upgrade open-webui

원하시면 제가 pip 설치용 + 환경변수 엔드포인트 자동 세팅이 포함된 실행 스크립트 를 만들어 드릴 수 있습니다.
그렇게 하면 매번 UI에서 입력할 필요 없이 엔드포인트와 키가 자동 등록된 상태로 Open WebUI가 실행됩니다.

Your system has an unsupported version of sqlite3. Chroma requires sqlite3 >= 3.35.0

이 오류는 Open WebUI가 내부에서 사용하는 Chroma DB 가 최신 SQLite 기능(3.35.0 이상)을 요구하는데,
현재 OS에 설치된 Python이 너무 구버전 SQLite 를 내장하고 있어서 발생하는 문제입니다.

pip install로 설치했을 때 Python은 내장된 sqlite3 라이브러리 를 사용하므로, OS에 sqlite3을 새로 깔아도 Python이 그걸 자동으로 쓰지 않습니다.
해결 방법은 크게 두 가지가 있습니다.

1) Python 자체를 최신 빌드로 교체 (권장)

가장 깔끔한 방법입니다. Python 3.10+ 최신 빌드는 sqlite3 3.35.0 이상을 포함합니다.

Ubuntu/Debian 예시

sudo apt update
sudo apt install python3.11 python3.11-venv python3.11-dev

그리고 새 venv에서 다시 설치:

python3.11 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install open-webui

macOS(Homebrew) 예시

brew install python@3.11
brew link python@3.11 --force

2) OS에 최신 sqlite3 설치 후 Python 재빌드

만약 Python 버전을 그대로 쓰고 싶다면:

최신 sqlite3 설치

Ubuntu/Debian:

sudo apt update
sudo apt install sqlite3 libsqlite3-dev

macOS:
```
brew install sqlite
```

Python을 재빌드하여 새 sqlite3을 링크
(소스 빌드 시 libsqlite3-dev를 설치한 상태여야 함)
```
pyenv install 3.11.9
pyenv global 3.11.9
```

3) conda 환경을 이용 (간단 대안)

conda는 최신 sqlite를 자동 포함하므로, 설치가 간단합니다.

conda create -n openwebui python=3.11
conda activate openwebui
pip install open-webui

💡 추천 순서

가능하면 Python을 최신으로 갈아타세요(방법 1).
OS-level sqlite만 업데이트해선 해결 안 되니, Python 재설치/재빌드가 필요합니다.
복잡하면 conda로 환경 만드는 게 제일 빠릅니다.

원하시면 제가 현재 OS/Python 버전과 sqlite 버전 확인 명령 을 드려서
지금 환경에서 어떤 경로가 제일 빠른지 바로 판단해드릴 수 있습니다.
그걸 해드릴까요?

현재 설치된 sqlite3 버전 보는 법 알려줘. 내가 설치한 파이썬이 3.11.12 라서 상당히 최신 버전인데. venv로 가상환경 만들어서 하고 있는데 이게 이슈가 될 수도 있나?

네, Python 3.11.12면 상당히 최신이지만,
venv 환경 안에서도 Python이 빌드될 때 포함된 SQLite 버전 을 그대로 쓰기 때문에,
OS의 sqlite 버전과는 별개로 문제가 날 수 있습니다.

확인 방법은 두 가지가 있습니다.

1) Python이 쓰는 sqlite3 버전 확인

가상환경 안에서 아래 명령 실행:

python -c "import sqlite3; print(sqlite3.sqlite_version)"

이 값이 3.35.0 이상 이어야 Chroma가 동작합니다.

2) OS 시스템 sqlite 버전 확인 (참고)

sqlite3 --version

이건 OS에 설치된 sqlite3 CLI 버전입니다.
Python 내부에서 사용하는 라이브러리 버전과 다를 수 있습니다.

💡 중요 포인트

venv는 현재 Python 실행 파일 과 그에 내장된 sqlite3를 그대로 복사해서 씁니다.
따라서 Python 3.11이라도, 해당 Python이 구버전 sqlite로 빌드되었으면 venv 안에서도 그대로 구버전을 씁니다.
해결하려면 최신 sqlite로 빌드된 Python을 쓰거나(예: pyenv, conda), 시스템 Python을 교체해야 합니다.

원하시면 제가 현재 venv에서 동작하는 sqlite 버전 확인 후, 바로 업그레이드 방법 까지 이어서 정리해 드릴까요?
그러면 바로 Chroma 오류도 해결됩니다.

그렇네 둘 다 3.26.0 으로 되고 있어. 내가 sudo 권한도 없고 인터넷 연결도 안 된 redhat 8.x OS야. 이거에 맞춰서 sqlite3 설치하고 파이썬 3.11 버전 다시 빌드 하는 방법 차근차근 알려줘

좋아요—sudo 없음 + 외부 인터넷 없음 + RHEL 8.x 환경을 전제로, 사용자 홈 디렉터리 에 최신 sqlite3를 소스에서 설치하고, 그걸 링크해서 Python 3.11을 다시 빌드 하는 절차를 완전 오프라인 기준으로 차근차근 정리했습니다.
(핵심은: Python이 링크하는 sqlite를 3.35.0 이상으로 교체하는 것!)

전체 흐름 한눈에

다른 네트워크 가능한 PC에서 소스 tar.gz 받아오기 → 사내망/USB로 서버에 복사
$HOME/opt/sqlite-<버전>에 sqlite3 설치 (사용자 권한)
그 sqlite를 가리키도록 환경변수(헤더/라이브러리 경로) 잡고 Python 3.11.12를 재빌드 + 사용자 경로에 설치
새 Python으로 venv 다시 만들고, python -c "import sqlite3; print(sqlite3.sqlite_version)"가 3.35+인지 확인

0) 준비: 디렉터리/변수

# 홈 디렉터리 아래에 설치 경로를 잡습니다.
mkdir -p $HOME/src $HOME/opt
# 아래 버전은 예시입니다. (3.45.3 등 3.35.0 이상이면 OK)
export SQLITE_VER=3.45.4
export PY_VER=3.11.12

# 설치 prefix
export SQLITE_PREFIX="$HOME/opt/sqlite-$SQLITE_VER"
export PY_PREFIX="$HOME/opt/python-$PY_VER"

1) 오프라인 파일 준비 (다른 PC에서 다운로드)

외부 인터넷 가능한 PC에서 아래 두 개(이상)를 받아 USB/사내망으로 서버의$HOME/src 로 옮깁니다.

SQLite : sqlite-autoconf-<X>.tar.gz
- 파일명 숫자 <X>는 버전 넘버를 붙인 값입니다. 예: 3.45.4 → 3450400
- 예시 파일명: sqlite-autoconf-3450400.tar.gz
Python 3.11.12 : Python-3.11.12.tgz

(선택) pip를 쓸 계획이면, 나중에 필요한 패키지들 whl/tar.gz 도 같이 받아오세요. 오프라인 설치 시 pip install --no-index --find-links로 설치합니다.

서버에 파일이 도착하면:

ls -1 $HOME/src
# sqlite-autoconf-3450400.tar.gz
# Python-3.11.12.tgz

2) sqlite3 (>=3.35) 사용자 디렉터리에 빌드/설치

cd $HOME/src
tar xf sqlite-autoconf-3450400.tar.gz
cd sqlite-autoconf-3450400

# fPIC으로 빌드, prefix는 사용자 디렉터리
CFLAGS="-O2 -fPIC" ./configure --prefix="$SQLITE_PREFIX"
make -j"$(nproc)"
make install

# 설치 확인
"$SQLITE_PREFIX/bin/sqlite3" --version
# 3.45.4 ... 같이 3.35.0 이상이 출력되어야 합니다.

3) Python 3.11.12를 새 sqlite에 링크해서 재빌드/설치

Python이 새 sqlite 헤더/라이브러리를 보도록 컴파일 환경변수 를 줍니다. 또한 실행 시 라이브러리 탐색이 되도록 rpath 를 심어두면 편합니다.

cd $HOME/src
tar xf Python-3.11.12.tgz
cd Python-3.11.12

# 컴파일러가 새 sqlite를 찾도록 경로 지정
export CPPFLAGS="-I$SQLITE_PREFIX/include"
export LDFLAGS="-L$SQLITE_PREFIX/lib -Wl,-rpath,$SQLITE_PREFIX/lib"
export LD_LIBRARY_PATH="$SQLITE_PREFIX/lib:$LD_LIBRARY_PATH"

# 최적화/ensurepip 포함하여 빌드
./configure --prefix="$PY_PREFIX" \
  --enable-optimizations \
  --with-lto \
  --with-ensurepip=install

make -j"$(nproc)"
make install

빌드가 끝난 뒤 경로 적용 & 버전 확인

# 새 파이썬을 PATH 앞에 두기 (쉘 프로필에 추가 권장)
export PATH="$PY_PREFIX/bin:$PATH"

# 파이썬이 바라보는 sqlite 버전 확인
python3 -c "import sqlite3; print(sqlite3.sqlite_version)"
# => 3.45.4 (또는 3.35.0 이상) 가 나와야 성공

만약 위에서 여전히 3.26.0이 나온다면, Python이 새 sqlite를 못 찾은 것입니다.

CPPFLAGS/LDFLAGS/LD_LIBRARY_PATH가 올바른지 점검

아래 “문제 해결 팁”의 A. _sqlite3 모듈 강제 구성 을 참고해 모듈을 명시적으로 빌드

4) 새 Python으로 venv 다시 만들기 (중요)

기존 venv는 예전 파이썬 바이너리/라이브러리 를 기준으로 만들어졌기 때문에 새로 만들어야 합니다.

# (선택) 이전 venv 비활성화
deactivate 2>/dev/null || true

# 새 venv 생성
python3 -m venv $HOME/venvs/openwebui
source $HOME/venvs/openwebui/bin/activate

# pip 자체 업그레이드 (오프라인이면 생략)
pip install --upgrade pip

# 최종 확인 (venv 내부에서도)
python -c "import sqlite3; print(sqlite3.sqlite_version)"
# => 3.35.0 이상인지 재확인

이제 이 venv에서 Open WebUI/Chroma를 쓰면 sqlite 버전 오류 없이 동작합니다.

5) (오프라인) pip 설치 팁

외부에서 의존성들을 미리 받아 왔다면:

# 오프라인 저장소 폴더(예: /path/pkgs)에 whl/tar.gz 모아둔 경우
pip install --no-index --find-links /path/pkgs open-webui

SSL 모듈(_ssl) 없이 빌드했다면 https 다운로드는 불가 하므로, 필요한 패키지는 사전 다운로드 가 필요합니다.
나중에 인터넷이 가능해지면 OpenSSL 헤더/라이브러리를 사용자 영역에 빌드한 뒤, Python을 다시 빌드해 _ssl 모듈을 붙일 수 있습니다(옵션).

문제 해결 팁 (Troubleshooting)

A) `_sqlite3` 모듈이 “not found”로 스킵되는 경우

Python 빌드 로그 마지막 부분에 “The necessary bits to build these optional modules were not found” 목록에 _sqlite3가 포함되어 있으면, SQLite 헤더/라이브러리를 못 찾은 것입니다. 가장 확실한 방법은 모듈 빌드 지시를 명시 하는 것입니다.

cd $HOME/src/Python-3.11.12/Modules

# Setup.local 파일에 명시적으로 _sqlite3 모듈 빌드 지시 추가
cat > Setup.local <<'EOF'
_sqlite3 _sqlite/module.c -I$SQLITE_PREFIX/include -L$SQLITE_PREFIX/lib -lsqlite3
EOF

# 환경변수는 여전히 설정된 상태여야 함 (CPPFLAGS/LDFLAGS/LD_LIBRARY_PATH)
cd ..
make -j"$(nproc)"
make install

다시 python -c "import sqlite3; print(sqlite3.sqlite_version)"로 확인해 보세요.

B) 매번 `LD_LIBRARY_PATH` 잡기 싫을 때

위에서 LDFLAGS="-Wl,-rpath,$SQLITE_PREFIX/lib"를 줬다면 보통은 필요 없습니다.
혹시 빠뜨렸다면, 아래처럼 rpath 포함 재빌드 하거나, 셸 프로필(~/.bashrc)에 다음을 추가하세요.

export PATH="$PY_PREFIX/bin:$PATH"
export LD_LIBRARY_PATH="$SQLITE_PREFIX/lib:$LD_LIBRARY_PATH"

C) 여러 버전 공존

다른 작업에 시스템 Python이 필요하면, 단순히 PATH/LD_LIBRARY_PATH를 활성화/비활성화 하여 전환하면 됩니다.
충돌을 피하려면 항상 which python으로 현재 쓰는 바이너리가 어디인지 확인하세요.

최종 체크리스트

$SQLITE_PREFIX/bin/sqlite3 --version이 3.35+
python -c "import sqlite3; print(sqlite3.sqlite_version)"가 3.35+
새 venv 에서 동일 결과 확인
Open WebUI/Chroma 다시 실행 시 더 이상 sqlite3 >= 3.35.0 에러가 나오지 않음

필요하면, 위 과정을 복붙 가능한 스크립트(버전/경로만 변수로 바꾸면 되는 형태)로 만들어 드릴게요.

혹시 이거 말고 다른 dependency가 있을까? 미리 다 준비해서 한 번에 설치하고 싶어.

좋은 질문이에요. “한 번에” 끝내려면 (A) Python 자체를 빌드할 때 필요한 네이티브 라이브러리 와 (B) Open WebUI/Chroma 파이썬 패키지 측 의존성(가능하면 휠로 미리 받아오기) 두 축으로 준비하면 됩니다. 아래를 차근차근 따라오세요.

A) Python 3.11을 기능 빠짐없이 빌드하기 위한 네이티브 의존성

목표: _sqlite3, _ssl, _bz2, _lzma, _readline, ctypes 등 표준 모듈이 빠지지 않게 하려면, 해당 C 라이브러리를 사용자 경로 에 먼저 설치하고, 그 경로를 가리키며 Python을 빌드해야 합니다. (sudo/인터넷 없음 가정)

필수/강력권장 라이브러리:

라이브러리	기능(파이썬 내 모듈)	없을 때 증상	오프라인 준비 요령(요지)
OpenSSL ≥1.1.1/3.0	`ssl`, `hashlib` 가속	HTTPS 불가 → pip 다운로드/인증서 문제	소스 tar.gz → `$HOME/opt/openssl-<ver>`에 설치 후 `./configure` 시 `--with-openssl` 또는 `CPPFLAGS/LDFLAGS`로 경로 지정
zlib	`zlib`	압축 관련 일부 기능 제한	`zlib` 소스 빌드 → `$HOME/opt/zlib`
bzip2 (libbz2)	`_bz2`	`.bz2` 핸들링 불가	`bzip2` 소스 빌드 → `$HOME/opt/bzip2`
xz (liblzma)	`_lzma`	`.xz` 핸들링 불가	`xz`(xz-utils) 소스 빌드 → `$HOME/opt/xz`
readline + ncurses	`readline`	REPL 히스토리/라인편집 미작동	`readline`, `ncurses` 소스 빌드
libffi	`_ctypes`	`ctypes` 미구성	`libffi` 소스 빌드
sqlite3 ≥3.35	`_sqlite3`	(이미 보신) Chroma 에러	위에서 진행하신 대로 소스 빌드
expat	`pyexpat`	XML 파싱 미동작	`expat` 소스 빌드
gdbm(선택)	`dbm.gnu`	GNU DBM 미사용	필요 시만
uuid(libuuid, 선택)	`uuid`(OS 백엔드)	순수 파이썬 대체	선택

설치 순서(권장)

zlib → bzip2 → xz → readline/ncurses → libffi → sqlite → OpenSSL → expat
각 라이브러리마다 --prefix="$HOME/opt/<name>-<ver>"로 설치
Python 빌드 전에 아래처럼 경로를 한 번에 잡습니다:

export PKGROOTS="$HOME/opt/zlib:$HOME/opt/bzip2:$HOME/opt/xz:$HOME/opt/readline:$HOME/opt/ncurses:$HOME/opt/libffi:$SQLITE_PREFIX:$HOME/opt/openssl:$HOME/opt/expat"
export CPPFLAGS="$(printf -- ' -I%s/include' ${PKGROOTS//:/ })"
export LDFLAGS="$(printf -- ' -L%s/lib' ${PKGROOTS//:/ }) -Wl,-rpath,$HOME/opt/zlib/lib:$HOME/opt/bzip2/lib:$HOME/opt/xz/lib:$HOME/opt/readline/lib:$HOME/opt/ncurses/lib:$HOME/opt/libffi/lib:$SQLITE_PREFIX/lib:$HOME/opt/openssl/lib:$HOME/opt/expat/lib"
export LD_LIBRARY_PATH="$HOME/opt/zlib/lib:$HOME/opt/bzip2/lib:$HOME/opt/xz/lib:$HOME/opt/readline/lib:$HOME/opt/ncurses/lib:$HOME/opt/libffi/lib:$SQLITE_PREFIX/lib:$HOME/opt/openssl/lib:$HOME/opt/expat/lib:$LD_LIBRARY_PATH"

그런 다음 Python ./configure:

./configure --prefix="$PY_PREFIX" \
  --enable-optimizations --with-lto \
  --with-ensurepip=install \
  --with-openssl="$HOME/opt/openssl-<ver>"  # 있으면 명시, 없으면 CPP/LDFLAGS에 의존
make -j"$(nproc)" && make install

빌드 후 확인(반드시 venv 새로 생성):
python -c "import sqlite3, ssl, bz2, lzma, readline, ctypes, xml.parsers.expat as e; print(sqlite3.sqlite_version, ssl.OPENSSL_VERSION)"

팁 : _sqlite3처럼 빠지는 모듈이 있다면, 위 경로/변수 누락이 원인입니다. 필요하면 Modules/Setup.local에 모듈 빌드 라인(예: _sqlite3 ... -lsqlite3)을 명시 하고 make install을 다시 실행하세요.

B) Open WebUI / Chroma 파이썬 패키지 쪽 의존성(오프라인 휠 준비)

목표: RHEL 8.x + Python 3.11에서 빌드 없이 설치 되도록, 가능한 한 미리 컴파일된 wheel(manylinux2014_x86_64 등)을 모아 오프라인 저장소(wheelhouse)를 준비합니다. (sudo/인터넷 없음 가정)

1) 핵심 패키지

open-webui (백엔드 FastAPI/uvicorn 등 포함)
chromadb (벡터DB: SQLite/duckdb + hnswlib 등)
다음은 종속성에 자주 포함되며 컴파일이 필요한 경우 가 있는 것들:
- hnswlib(C++11)
- uvloop, httptools, watchfiles(C/Rust 빌드 필요 가능)
- orjson(Rust) 또는 ujson(C)
- numpy, scipy, pandas (BLAS 연동/컴파일 이슈 → 반드시 wheel 로)
- pydantic, fastapi, starlette, uvicorn 등은 보통 pure-Python이지만, uvicorn[standard]라면 위 네이티브 패키지를 추가로 끌어옵니다.

2) 오프라인 다운로드(사전 준비) 방법

외부 인터넷 가능한 동일/유사 리눅스(x86_64, glibc) 머신 에서:

python3.11 -m venv dl && source dl/bin/activate
pip install --upgrade pip wheel

# 목적지 폴더
mkdir -p /tmp/wheelhouse

# 가장 쉬운 방법: 직접 종속성을 해석하게 맡김
pip download --dest /tmp/wheelhouse open-webui chromadb

# 만약 아키텍처가 다르거나 강제로 휠만 받고 싶다면 (고급)
pip download --only-binary=:all: \
  --platform manylinux2014_x86_64 --implementation cp --python-version 311 \
  --dest /tmp/wheelhouse open-webui chromadb

오류가 나면, 메시지에 나온 패키지를 개별적으로 추가 해 다시 pip download 하세요(예: numpy, hnswlib, orjson 등).
Rust toolchain 없이 설치하려면 반드시 orjson, watchfiles 등 미리 빌드된 wheel 을 확보해야 합니다.

서버로 복사 후, 오프라인 설치:

pip install --no-index --find-links /path/to/wheelhouse open-webui chromadb

3) Chroma(Chromadb) 관련 주의점

현재 에러의 원인인 sqlite3 ≥ 3.35 는 이미 A)에서 해결.
hnswlib 휠이 없으면 소스 빌드가 시도됩니다(오프라인/컴파일러 문제로 실패하기 쉬움). 반드시 휠로 가져오세요.
성능을 위해 numpy도 휠 을 강력 추천합니다. (소스 빌드는 BLAS/LAPACK 등 추가 지뢰가 많음)

C) 도구 체인(컴파일러 등)

필수 : gcc, g++, make, tar, xz, patch, pkg-config
- 대부분 RHEL 8에는 기본 제공되지만, 만약 사용자 PATH에 없다면 관리자에게 설치 요청 필요합니다(이 부분은 sudo/오프라인 환경에서 사용자 설치가 현실적으로 어렵습니다).
선택(소스 빌드 많을 때 유용): cmake(일부 라이브러리), ninja(선택)

D) “한 번에 끝내기” 체크리스트

(외부 PC) 아래 소스/휠 다운로드
- 소스: sqlite, openssl, zlib, bzip2, xz, readline, ncurses, libffi, expat, Python-3.11.12.tgz
- 휠: open-webui, chromadb, hnswlib, numpy, uvicorn, fastapi, pydantic, starlette, watchfiles, orjson(또는 ujson), 기타 자동으로 끌려오는 것들 전부
(서버) A 순서대로 네이티브 라이브러리 를 $HOME/opt/...에 설치
(서버) 환경변수로 include/lib/rpath 셋업 후 Python 빌드
(서버) 새 venv 생성 → pip install --no-index --find-links …로 휠 설치
python -c "import sqlite3; print(sqlite3.sqlite_version)"가 3.35+인지 확인
open-webui serve 실행 테스트

필요하시면, 위 라이브러리들 오프라인 빌드 자동화 스크립트(하나의 bash 파일)와, pip wheelhouse 만들기용 명령어 세트 를 사용자 환경에 맞춰 뽑아드릴게요. 어떤 버전 조합으로 가실지 알려주시면 바로 만들어 드립니다.

으악 너무 많아. 저것들이 다 꼭 필요한거야? 난 오류만 안나면 돼

확실히 많았죠 😂 “오류만 안 나게”가 목표라면 딱 하나만 해결하면 됩니다:

핵심만: SQLite만 새로 깔고, Python을 그걸로 다시 빌드

Chroma 에러의 직접 원인 은 sqlite3 < 3.35뿐이에요.
즉, 다른 라이브러리들을 전혀 건드리지 않아도 됩니다.

0) 변수/폴더

mkdir -p $HOME/src $HOME/opt
export SQLITE_VER=3.45.4              # 3.35.0 이상이면 OK
export PY_VER=3.11.12

export SQLITE_PREFIX="$HOME/opt/sqlite-$SQLITE_VER"
export PY_PREFIX="$HOME/opt/python-$PY_VER"

1) (오프라인에서 가져온) 소스 업로드

sqlite-autoconf-<NNNNNNN>.tar.gz (예: 3.45.4 → 3450400)
Python-3.11.12.tgz
이 두 개만 있으면 충분합니다.

2) SQLite만 사용자 경로에 설치

cd $HOME/src
tar xf sqlite-autoconf-3450400.tar.gz
cd sqlite-autoconf-3450400

CFLAGS="-O2 -fPIC" ./configure --prefix="$SQLITE_PREFIX"
make -j"$(nproc)"
make install

"$SQLITE_PREFIX/bin/sqlite3" --version    # 3.35.0 이상 확인

3) Python을 “그 SQLite”로만 링크해서 재빌드

cd $HOME/src
tar xf Python-3.11.12.tgz
cd Python-3.11.12

# 컴파일러가 새 sqlite를 보게 경로 지정 + rpath 심기
export CPPFLAGS="-I$SQLITE_PREFIX/include"
export LDFLAGS="-L$SQLITE_PREFIX/lib -Wl,-rpath,$SQLITE_PREFIX/lib"
export LD_LIBRARY_PATH="$SQLITE_PREFIX/lib:$LD_LIBRARY_PATH"

./configure --prefix="$PY_PREFIX" --with-ensurepip=install
make -j"$(nproc)"
make install

4) 경로 적용 + 버전 확인

export PATH="$PY_PREFIX/bin:$PATH"

python3 -c "import sqlite3; print(sqlite3.sqlite_version)"
# >>> 3.35.0 이상 나오면 끝!

5) venv 새로 만들기 (중요)

python3 -m venv $HOME/venvs/openwebui
source $HOME/venvs/openwebui/bin/activate
python -c "import sqlite3; print(sqlite3.sqlite_version)"  # 다시 3.35+ 확인

이제 같은 에러 없이 Open WebUI / Chroma 돌릴 수 있습니다.

혹시 생길 수 있는 “딱 두 가지” 추가 오류만 메모

ssl 모듈 없다는 에러 → 온라인 pip 필요할 때만 발생. 지금은 오프라인이라면 무시해도 OK.
readline 히스토리 안 먹음 → 기능상 불편이지만 치명적 아님. 필요할 때만 나중에 해결.

요약: 지금은 SQLite만 해결하세요. 나머지는 문제 생기면 그때 최소만 붙이면 돼요.

원하면 위 절차를 복붙용 한 파일 스크립트 로 묶어 드릴게요.

sqlite Precomiled Binary가 있는데 그냥 이거 받아서 써도 되나?

네, 전제 조건만 맞으면 Precompiled Binary(미리 컴파일된 sqlite3) 써도 됩니다.
다만 Python은 실행 시 시스템 PATH에 있는 sqlite3 CLI가 아니라, 빌드 시점에 링크된 libsqlite3.so 를 씁니다.

즉, 단순히 sqlite3 실행파일만 받아서 두는 건 의미 없고, 라이브러리(.so)와 헤더(.h) 까지 있어야 합니다.

1) 필요한 구성 요소

SQLite precompiled package 안에 보통 다음이 있어야 합니다:

sqlite3 실행파일 (CLI)
libsqlite3.so (또는 .a)
sqlite3.h 등 개발용 헤더 파일

만약 제공된 게 CLI 실행파일만 이라면 → Python 재빌드에는 못 씁니다.

2) 쓸 수 있는 경우

precompiled bundle이 include/ 와 lib/ 디렉터리를 함께 제공
libsqlite3.so가 3.35.0 이상
해당 빌드가 RHEL 8.x glibc 호환

설치 예:

mkdir -p $HOME/opt/sqlite-prebuilt
tar xf sqlite-precompiled.tar.gz -C $HOME/opt/sqlite-prebuilt

export SQLITE_PREFIX="$HOME/opt/sqlite-prebuilt"
export CPPFLAGS="-I$SQLITE_PREFIX/include"
export LDFLAGS="-L$SQLITE_PREFIX/lib -Wl,-rpath,$SQLITE_PREFIX/lib"
export LD_LIBRARY_PATH="$SQLITE_PREFIX/lib:$LD_LIBRARY_PATH"

# 이후 Python 빌드
cd Python-3.11.12
./configure --prefix="$HOME/opt/python-3.11.12" --with-ensurepip=install
make -j"$(nproc)"
make install

3) 주의할 점

precompiled binary의 .so 파일이 정적 경로(/usr/lib 등)에 깔린 게 아니므로,
실행 시 LD_LIBRARY_PATH 또는 rpath로 경로를 알려줘야 합니다.
glibc 버전 호환성이 안 맞으면 symbol not found 같은 런타임 오류가 날 수 있습니다.
Python 빌드 시 _sqlite3 모듈이 안 잡히면, 헤더(sqlite3.h) 경로가 CPPFLAGS에 잡혀 있는지 확인해야 합니다.

📌 결론:

라이브러리+헤더 포함된 패키지 면 문제 없이 사용 가능
CLI만 있는 패키지는 Chroma 문제 해결 불가
Python 빌드시 새 sqlite를 명시적으로 링크해야만 적용됨

원하시면, 제가 precompiled binary가 쓸 수 있는지 체크하는 명령어 세트 를 드릴 수 있습니다.
그걸로 지금 가지고 있는 패키지가 Python 빌드에 바로 쓸 수 있는지 바로 확인할 수 있어요.
그거 드릴까요?

응 so가 없네

그럼 그 precompiled binary는 Python 빌드에는 못 씁니다.

Python이 사용하는 _sqlite3 모듈은

sqlite3.h(헤더 파일)
libsqlite3.so(공유 라이브러리)

이 두 가지가 빌드 시점에 필요 합니다.
CLI 실행파일(sqlite3)만으로는 전혀 적용이 안 돼요.
그래서 결국 SQLite 소스를 받아서 직접 빌드해야 합니다.

📌 정리

지금 상황(so 없음) → Python 재빌드 시 구버전 시스템 라이브러리를 그대로 링크 → Chroma 에러 재발
해결 방법 → SQLite 소스 tar.gz 받아서 $HOME/opt/sqlite-<ver>에 설치 후, Python 빌드할 때 그 경로를 연결

원하면 제가 딱 SQLite만 빌드하고 Python에 붙이는 최소 스크립트**를 만들어서
그대로 복붙해서 쓰면 되게 해드릴까요?
그렇게 하면 다른 의존성 건드릴 필요 없이 한 번에 끝납니다.

sqlite 빌드할 때 내가 설치한 GCC 사용하고 싶어.

좋지! sudo 없이, 내가 설치한 GCC로만 SQLite를 빌드해서 .so까지 만들고, 그걸로 파이썬을 다시 빌드하는 최소 절차를 딱 정리해줄게. (RHEL 8.x, 오프라인 가정)

0) 전제: 내가 설치한 GCC 위치

아래처럼 경로만 너 환경에 맞게 바꿔줘.

# 내가 설치한 GCC 루트(예: $HOME/opt/gcc-12.3.0)
export TOOLCHAIN_ROOT="$HOME/opt/gcc-12.3.0"

# PATH와 런타임 라이브러리 경로(중요)
export PATH="$TOOLCHAIN_ROOT/bin:$PATH"
export LD_LIBRARY_PATH="$TOOLCHAIN_ROOT/lib64:$TOOLCHAIN_ROOT/lib:$LD_LIBRARY_PATH"

# 확인
which gcc
gcc --version

필요하면 binutils까지 같이 쓴다는 의미로 AR/RANLIB/LD도 지정 가능:
export AR="$TOOLCHAIN_ROOT/bin/ar"; export RANLIB="$TOOLCHAIN_ROOT/bin/ranlib"

1) SQLite를 “내 GCC”로 빌드(+공유 라이브러리 .so 생성)

오프라인으로 가져온 sqlite-autoconf-<NNNNNNN>.tar.gz 기준.

# 설치 위치(원하는 곳으로)
export SQLITE_PREFIX="$HOME/opt/sqlite-3.45.4"

mkdir -p "$HOME/src" "$SQLITE_PREFIX"
cd "$HOME/src"
tar xf sqlite-autoconf-3450400.tar.gz
cd sqlite-autoconf-3450400

# ★ 핵심: CC를 내 GCC로 지정, -fPIC, rpath까지 준비
export CC="$TOOLCHAIN_ROOT/bin/gcc"
export CFLAGS="-O2 -fPIC \
-DSQLITE_ENABLE_FTS5 \
-DSQLITE_ENABLE_JSON1 \
-DSQLITE_ENABLE_COLUMN_METADATA \
-DSQLITE_ENABLE_RTREE \
-DSQLITE_THREADSAFE=1"
export LDFLAGS="-Wl,-rpath,$SQLITE_PREFIX/lib"

# configure → build → install
./configure --prefix="$SQLITE_PREFIX" --enable-shared --disable-static
make -j"$(nproc)"
make install

# 검증
"$SQLITE_PREFIX/bin/sqlite3" --version            # 3.35.0 이상
ls -l "$SQLITE_PREFIX/lib/libsqlite3.so"          # .so 존재 확인
ldd "$SQLITE_PREFIX/lib/libsqlite3.so" | head     # 내 GCC의 libgcc_s 등 링크 확인

TIP

--enable-shared로 .so 생성 확실히.

rpath는 나중에 파이썬이 이 .so를 찾을 수 있게 하는 안전장치.

만약 ldd에서 이상한 시스템 lib로 엮이면 LD_LIBRARY_PATH가 제대로 잡혔는지 다시 확인.

2) 파이썬을 “그 SQLite .so/헤더”로 링크해서 재빌드

# 파이썬 설치 경로
export PY_PREFIX="$HOME/opt/python-3.11.12"

# 컴파일/링크에 SQLite 경로 반영 + 런타임 rpath
export CPPFLAGS="-I$SQLITE_PREFIX/include"
export LDFLAGS="-L$SQLITE_PREFIX/lib -Wl,-rpath,$SQLITE_PREFIX/lib"
export LD_LIBRARY_PATH="$SQLITE_PREFIX/lib:$TOOLCHAIN_ROOT/lib64:$TOOLCHAIN_ROOT/lib:$LD_LIBRARY_PATH"

# (옵션) 파이썬도 내 GCC로
export CC="$TOOLCHAIN_ROOT/bin/gcc"

cd "$HOME/src"
tar xf Python-3.11.12.tgz
cd Python-3.11.12

./configure --prefix="$PY_PREFIX" --with-ensurepip=install
make -n > /dev/null 2>&1  # (캐시 생성용 살짝 돌리기; 생략 가능)
make -j"$(nproc)"
make install

# PATH 적용 및 확인
export PATH="$PY_PREFIX/bin:$PATH"
python3 -c "import sqlite3; print(sqlite3.sqlite_version)"
# ==> 3.35.0 이상 나오면 성공!

만약 _sqlite3가 빠졌다는 메시지가 나오면:
CPPFLAGS/LDFLAGS/LD_LIBRARY_PATH가 맞는지 확인
필요 시 Modules/Setup.local에 아래 한 줄 추가 후 make install 다시 실행
bash
    
_sqlite3 _sqlite/module.c -I$SQLITE_PREFIX/include -L$SQLITE_PREFIX/lib -lsqlite3
    

3) venv 새로 만들기 (중요)

기존 venv는 구버전 파이썬 기준이므로 새로 생성해야 해.

python3 -m venv $HOME/venvs/openwebui
source $HOME/venvs/openwebui/bin/activate
python -c "import sqlite3; print(sqlite3.sqlite_version)"  # 3.35+ 재확인

자주 묻는 포인트 (진짜 핵심만)

Q. 그냥 sqlite3 실행파일만 있으면 안 돼?
A. 안 돼. 파이썬 빌드에는 libsqlite3.so + sqlite3.h가 필요.
Q. 꼭 내 GCC여야 하나?
A. 네. 네이티브 툴체인 혼용하면 런타임에 symbol not found 날 수 있음. PATH/LD_LIBRARY_PATH를 내 GCC로 먼저 잡아.
Q. rpath 꼭 넣어야 해?
A. 강추. 그러면 이후에 LD_LIBRARY_PATH 깜박해도 파이썬이 libsqlite3.so를 바로 찾음.

필요하면 위 과정을 복붙만 하면 되는 단일 bash 스크립트 로 만들어 줄게. 경로랑 버전만 바꾸면 바로 돌아가게!

-W1,-rpath 이건 뭐하는 옵션이야?

아마 제가 적은 건 -Wl,-rpath 인데, 그건 타이핑이 조금 비슷해서 헷갈린 걸 거예요.
(-W1은 의미 없고, -Wl이 맞습니다. 여기서 소문자 L은 “linker”의 L)

`-Wl,-rpath,<경로>` 의미

-Wl,
- gcc나 g++ 같은 컴파일 드라이버에 링커 옵션을 그대로 전달 하라는 뜻입니다.
- 즉, -Wl,옵션 → “이 옵션은 링커(ld)에게 주는 거야”라는 의미.
-rpath,<경로>
- 런타임 라이브러리 검색 경로 를 바이너리에 직접 박아 넣음.
- 실행 파일이 만들어질 때 ELF 헤더의 RPATH(또는 RUNPATH)에 <경로>를 기록합니다.
- 그래서 실행할 때 LD_LIBRARY_PATH를 따로 안 잡아도 해당 경로에서 .so를 자동으로 찾습니다.

예시

gcc main.c -L$HOME/opt/sqlite/lib -lsqlite3 \
    -Wl,-rpath,$HOME/opt/sqlite/lib

-L… : 빌드할 때 라이브러리 검색 경로
-Wl,-rpath,… : 실행할 때도 이 경로를 기억해서 libsqlite3.so 찾음

왜 Python/SQLite 빌드에 쓰나?

홈 디렉토리 같은 비표준 경로 에 설치한 .so는 기본 런타임 경로에 없어요.
매번 LD_LIBRARY_PATH=$HOME/opt/sqlite/lib 설정하는 건 번거롭죠.
-Wl,-rpath를 빌드 시 넣어두면 그 파이썬 실행 파일이 항상 그 경로에서 먼저 .so를 찾게 됩니다.

원하시면 제가 LD_LIBRARY_PATH 없이도 동작하게 rpath 넣은 Python+SQLite 빌드 스크립트를 바로 만들어드릴게요.
그럼 환경변수 깜빡해도 안전합니다.

근데 sqlite할 때도 LDFLAGS를 넣어줘야해?

SQLite 빌드할 때는 상황에 따라 다릅니다 👍

1. 기본적으로는 LDFLAGS 없어도 빌드됨

SQLite 자체는 외부 라이브러리 의존성이 거의 없어요.
./configure --prefix=…만으로도 libsqlite3.so 잘 만들어집니다.
그래서 순수 SQLite 빌드 라면 LDFLAGS를 안 줘도 무방합니다.

2. 그런데 내가 원하는 rpath를 박고 싶다면 LDFLAGS 필요

SQLite를 설치한 비표준 경로 를 Python 빌드 시 LD_LIBRARY_PATH 없이 사용하고 싶으면,
SQLite를 빌드할 때도 .so 안에 rpath를 넣을 수 있습니다.
예:

export LDFLAGS="-Wl,-rpath,$SQLITE_PREFIX/lib"

이렇게 하면 SQLite CLI(sqlite3)나 SQLite를 링크한 프로그램이 실행될 때
$SQLITE_PREFIX/lib를 자동으로 검색합니다.

3. Python 빌드에서는 LDFLAGS 필수

Python이 _sqlite3 모듈을 만들 때 libsqlite3.so를 어디서 찾을지 알아야 해서,
Python 빌드할 때는 반드시
```
export LDFLAGS="-L$SQLITE_PREFIX/lib -Wl,-rpath,$SQLITE_PREFIX/lib"
```

처럼 넣어주는 게 안전합니다.

-L… → 컴파일/링크 시 검색 경로
-Wl,-rpath,… → 런타임 검색 경로

✅ 정리

SQLite 빌드: LDFLAGS 없이도 가능. rpath를 넣고 싶으면 추가.
Python 빌드: LDFLAGS 필수. 최소한 -L<sqlite lib> + -Wl,-rpath,<sqlite lib>는 꼭 넣어야 안전.

원하면 제가 SQLite 빌드 때 rpath 없이, Python 빌드 때만 rpath 넣는 최소 설치 스크립트 를 바로 짜 드릴 수 있습니다.
그렇게 하면 불필요한 옵션은 안 쓰면서도 Python에서만 경로를 기억하게 할 수 있어요.

그런데 왜 이렇게 설정할 것이 많아? configure의 default로 어느정도 reasonable한 설정이 들어가있는거 아니야?

맞아요 — ./configure가 이미 꽤 reasonable한 기본값 을 넣어주긴 합니다.

그런데 우리가 지금 설정을 많이 건드리는 이유는 기본값이 "시스템에 이미 깔린 것" 기준 이기 때문이에요.
RHEL 8처럼 오래된 OS + sudo 불가 환경에서는 그 기본값이 원하는 최신 라이브러리를 전혀 안 봅니다.

1. `configure`의 기본 동작

./configure는 PATH와 표준 라이브러리 경로(/usr/include, /usr/lib64 등)에서 헤더와 .so를 찾습니다.
최신 라이브러리를 비표준 경로($HOME/opt/...)에 설치해도, 특별히 알려주지 않으면 그냥 무시하고 시스템 기본 구버전을 씁니다.
예: Python이 _sqlite3 모듈을 빌드할 때 /usr/include/sqlite3.h + /usr/lib64/libsqlite3.so를 찾아서 링크 → 결과적으로 3.26.0.

2. 왜 우리가 CPPFLAGS/LDFLAGS를 주나?

"야, 헤더는 여기 있다!" → CPPFLAGS="-I$SQLITE_PREFIX/include"
"라이브러리는 여기 있다!" → LDFLAGS="-L$SQLITE_PREFIX/lib"
"실행할 때도 여기서 찾아라!" → -Wl,-rpath,$SQLITE_PREFIX/lib
이걸 안 하면, 빌드 시 컴파일러는 최신 헤더를 못 보고 ,
실행 시 런타임 로더는 최신 .so를 못 찾습니다.

3. rpath까지 넣는 이유

기본적으로 실행 시 .so는 /lib, /usr/lib, LD_LIBRARY_PATH에서 찾습니다.
홈 디렉토리에 깔린 .so는 기본 검색 경로에 없어요.
매번 LD_LIBRARY_PATH를 세팅하지 않으려면 rpath로 박아두는 게 편리.

4. 요약 비유

기본 configure는 "부엌(시스템 기본 경로)에 있는 재료만" 씁니다.
우리가 한 건 "냉장고(홈 디렉토리)에 있는 최신 재료도 써!" 하고 경로를 알려주는 거예요.

원하면 제가 이 경로 설정을 최소화해서, SQLite 최신판만 쓰게 하는 configure 예제 를 아주 간단히 정리해 드릴까요?
그러면 지금처럼 CPPFLAGS/LDFLAGS를 여러 줄 쓰지 않고도 깔끔하게 됩니다.

아니 rpath나 라이브러리는 다 이해해 export CFLAGS="-O2 -fPIC \ -DSQLITE_ENABLE_FTS5 \ -DSQLITE_ENABLE_JSON1 \ -DSQLITE_ENABLE_COLUMN_METADATA \ -DSQLITE_ENABLE_RTREE \ -DSQLITE_THREADSAFE=1" 이거는 좀 귀찮아서 안넣었어 근데

괜찮아—저 플래그들(FTS5/JSON1/RTREE/COLUMN_METADATA/THREADSAFE)은 “기능 토글”일 뿐이고, Chroma + Open WebUI가 돌아가는데 필수는 아니야.
현재 목표(에러만 안 나게)는 버전 ≥ 3.35.0 이 핵심이고, 빌드에선 -fPIC 정도만 챙기면 충분합니다.

결론 먼저

지금 당장은 CFLAGS="-O2 -fPIC" 만 줘도 OK.
추가 기능이 필요할 때만 그때 다시 켜면 됩니다. (다시 빌드해도 Python 쪽 큰 수정 필요 없음)

각 옵션이 실제로 뭘 켜는지 (필요할 때만!)

SQLITE_ENABLE_FTS5 : 풀텍스트 검색(FTS5) 엔진. 대부분의 앱에 필수 아님.
SQLITE_ENABLE_JSON1 : JSON 함수(json_extract 등). 쿼리에서 JSON 다룰 때만 필요.
SQLITE_ENABLE_RTREE : R-Tree 인덱스(공간/범위). 특수한 경우에만.
SQLITE_ENABLE_COLUMN_METADATA : 컬럼 메타데이터 API. 일반 사용엔 거의 불필요.
SQLITE_THREADSAFE=1 : 스레드 세이프. 기본값이 1 이므로 굳이 지정 안 해도 됨.

“최소 안전” 빌드 예시

# 최소만: 성능 + 공유라이브러리 생성
CFLAGS="-O2 -fPIC" \
./configure --prefix="$SQLITE_PREFIX" --enable-shared --disable-static
make -j"$(nproc)" && make install

나중에 기능이 필요해지면(선택)

귀찮은 매크로 대신 configure 플래그 로 켜도 됩니다:

CFLAGS="-O2 -fPIC" \
./configure --prefix="$SQLITE_PREFIX" --enable-shared --disable-static \
  --enable-fts5 --enable-json1 --enable-rtree
make -j"$(nproc)" && make install

(= 내부적으로 위 매크로들을 정의해줍니다)

현재 빌드에 뭐가 켜졌는지 확인

$SQLITE_PREFIX/bin/sqlite3 -cmd "PRAGMA compile_options;" ":memory:" ".quit"
# 또는
$SQLITE_PREFIX/bin/sqlite3 -line ":memory:" "PRAGMA compile_options;"

여기에 ENABLE_FTS5, ENABLE_JSON1 같은 항목이 뜨면 켜진 것.

요약

지금은 CFLAGS 최소(-O2 -fPIC)만 넣고 진행해도 무방.
Chroma 에러는 “버전” 이슈였고, 부가 기능 플래그는 필수 아님.
나중에 필요해지면 --enable-fts5/json1/rtree로 다시 빌드하면 끝.

no such module: fts5 enable 을 해야하나본

맞아요—그 메시지는 FTS5가 꺼져 있어서 나는 거예요.
이미 한 번 빌드하셨다면, SQLite만 다시 컴파일 해서 libsqlite3.so를 교체하면 됩니다. (Python은 다시 안 빌려도 됨—같은 경로의 .so를 런타임에 쓰니까요)

빠른 해결 (컴파일에 포함시키는 방법)

아래처럼 --enable-fts5만 추가해서 다시 빌드·설치 하세요.

# 전제: 이전과 같은 PREFIX를 사용 (예: $SQLITE_PREFIX)
cd $HOME/src/sqlite-autoconf-3450400   # 소스 디렉터리로 이동

# (내 GCC를 쓰는 중이라면) CC/LD_LIBRARY_PATH를 이전과 동일하게 잡아두세요.
# export CC="$TOOLCHAIN_ROOT/bin/gcc"
# export LD_LIBRARY_PATH="$TOOLCHAIN_ROOT/lib64:$LD_LIBRARY_PATH"

# 최소 옵션 + FTS5만 켜기
CFLAGS="-O2 -fPIC" \
./configure --prefix="$SQLITE_PREFIX" \
  --enable-shared --disable-static \
  --enable-fts5

make -j"$(nproc)"
make install

켜졌는지 확인

"$SQLITE_PREFIX/bin/sqlite3" -line ":memory:" "PRAGMA compile_options;"
# 출력에 ENABLE_FTS5 가 보이면 OK

간단 실전 테스트

"$SQLITE_PREFIX/bin/sqlite3" <<'SQL'
CREATE VIRTUAL TABLE t USING fts5(content);
INSERT INTO t(content) VALUES ('hello world'), ('hello sqlite'), ('fts5 works');
SELECT rowid, content FROM t WHERE t MATCH 'hello';
SQL

Python 쪽도 되는지 확인

rpath 또는 LD_LIBRARY_PATH가 이미 잡혀 있다면, Python은 자동으로 새 libsqlite3.so 를 사용합니다.

python - <<'PY'
import sqlite3
con = sqlite3.connect(':memory:')
con.execute("CREATE VIRTUAL TABLE t USING fts5(content)")
con.executemany("INSERT INTO t(content) VALUES (?)", [('hello world',), ('hello sqlite',), ('fts5 works',)])
print(list(con.execute("SELECT rowid, content FROM t WHERE t MATCH 'hello'")))
PY

참고 (옵션)

JSON 함수도 필요하면 다음처럼 같이 켤 수 있어요:

CFLAGS="-O2 -fPIC" ./configure --prefix="$SQLITE_PREFIX" \
  --enable-shared --disable-static \
  --enable-fts5 --enable-json1

재빌드 후 Python 재설치는 불필요 합니다. 단, 다른 경로 에 설치했다면 LD_LIBRARY_PATH나 -Wl,-rpath,<경로>로 새 경로를 보이게 해야 해요.

필요하면 위 과정을 한 번에 도는 짧은 스크립트 로 묶어 드릴게요.

OperationalError: table embeddings already exists

오류 메시지 그대로 해석하면, 지금 사용 중인 SQLite DB 안에 embeddings 테이블이 이미 있어서 새로 만드는 쿼리(아마 CREATE TABLE embeddings (...))가 다시 실행되며 터진 겁니다. 보통 ① 같은 DB 파일을 두 번 초기화했거나, ② 예전 데이터가 남아 있는데 마이그레이션 로직이 IF NOT EXISTS 없이 실행될 때 생겨요.

아래 중 편한 걸로 해결하세요 — “에러만 안 나게” 기준으로 가장 빨리 끝나는 순서 예요.

1) 가장 빠름: 새 데이터 디렉터리/DB로 시작

(Open WebUI/Chroma가 쓰는 데이터 폴더 만 새로 쓰면 바로 해결)

# 예: Open WebUI를 새 데이터 폴더로
open-webui serve --data-dir "$HOME/openwebui-data-clean"

혹은(Chroma를 직접 쓰는 경우):

# Chroma 영속 디렉터리를 새로
export CHROMA_PERSIST_DIRECTORY="$HOME/chroma-data-clean"
# 앱/스크립트 재실행

장점: 기존 파일 건드리지 않음.
단점: 이전 대화/인덱스는 새 폴더로 분리됨(필요하면 나중에 옮길 수 있음).

2) 기존 DB에서 해당 테이블만 삭제

“그 DB 파일을 그대로 쓰되, 충돌 테이블만 정리”하는 방법입니다. (데이터가 날아갈 수 있으니 진짜 필요 없을 때만)

# DB 파일 위치 파악
# (예: open-webui의 --data-dir 안, chroma.sqlite / chroma.db / app.db 등)
# 못 찾겠으면:
# find "$HOME" -maxdepth 3 -type f \( -name "*.db" -o -name "*.sqlite*" \)

# 스키마 확인
sqlite3 /path/to/your.db ".tables"
sqlite3 /path/to/your.db ".schema embeddings"

# 정말 삭제해도 되는지 건수 확인
sqlite3 /path/to/your.db "SELECT COUNT(*) FROM embeddings;"

# 삭제 (주의: 복구 어려움)
sqlite3 /path/to/your.db "DROP TABLE embeddings;"

그 다음 앱을 다시 실행해 보세요. 초기화/마이그레이션 단계에서 테이블을 다시 만들 겁니다.

3) 코드/설정 쪽에서 “이미 있으면 건너뛰기”

만약 직접 작성한 스크립트 가 테이블을 만드는 거라면, 쿼리를 바꿔주세요:

sql

CREATE TABLE IF NOT EXISTS embeddings ( ... );

(가상 테이블 FTS5의 경우엔 CREATE VIRTUAL TABLE IF NOT EXISTS 지원 버전이 제한적일 수 있으니, 확실히 하려면 실행 전에 존재 여부를 체크해서 분기하세요.)

체크 포인트 (왜 다시 생겼는지)

같은 DB 파일을 두 프로세스가 각각 “초기화” 로직으로 시작 → 충돌.
예전 버전/다른 앱이 같은 DB 파일을 사용 → 스키마 이름 겹침.
마이그레이션 스크립트에 IF NOT EXISTS가 빠짐.

필요하면 지금 쓰는 DB 파일 경로를 같이 점검 하고, “드랍 vs 새 폴더로 시작” 중 어떤 게 안전한지 바로 판단해 드릴게요. 사용 중인 데이터 디렉터리/DB 파일 경로만 알려주면 됩니다.

openwebui를 분리된 공간망에서 서비스할거야. 뭐 따로 옵션을 주거나 해야할 것 있어?

좋아—분리된 폐쇄망(air‑gapped/내부망)에서 Open WebUI를 안정적으로 돌릴 때 “꼭 챙기면 좋은 옵션”만 딱 정리해 줄게. 전부 pip 실행 기준이지만 Docker/쿠버네티스도 동일한 ENV 개념이야.

핵심만 6줄 요약

OFFLINE_MODE 켜서 버전체크/외부 다운로드 비활성화
내부 도메인으로 WEBUI_URL 지정(SSO/리다이렉트용)
회원가입/권한 통제 : ENABLE_SIGNUP, DEFAULT_USER_ROLE
웹검색/RAG 외부 호출 을 꺼두거나 내부 검색엔진만 허용
모델/임베딩 은 미리 캐시(모델 파일을 내부 경로에 준비)
PersistentConfig 주의 : 처음 값이 DB에 저장됨(바꾸려면 UI에서 수정)

이게 전부야. 아래에 바로 쓸 수 있는 예시 붙일게.

최소 권장 환경변수 (폐쇄망 안전판)

# 1) 오프라인 모드: 버전 체크/허깅페이스 자동 다운 등 비활성화
export OFFLINE_MODE=True  # 오프라인 동작 가이드에 명시됨 :contentReference[oaicite:0]{index=0}

# 2) 내부 URL 명시(SSO/리다이렉트, 일부 기능에서 필수)
export WEBUI_URL="https://openwebui.internal.example"  # PersistentConfig 항목 :contentReference[oaicite:1]{index=1}

# 3) 사용자 만들기 정책
export ENABLE_SIGNUP=False                  # 신규 가입 막기(초기 관리자만) :contentReference[oaicite:2]{index=2}
export DEFAULT_USER_ROLE="pending"          # 가입 허용 시에도 기본은 보류 권장 :contentReference[oaicite:3]{index=3}

# 4) 웹검색 완전 차단(기본 False지만, 명시해 두면 좋음)
export ENABLE_WEB_SEARCH=False              # 웹검색 토글(퍼시스턴트) :contentReference[oaicite:4]{index=4}

# 5) CORS/쿠키(내부 HTTPS라면 Secure 쿠키 사용 권장)
export CORS_ALLOW_ORIGIN="https://openwebui.internal.example"  # 기본은 * → 내부만 허용으로 조이기 :contentReference[oaicite:5]{index=5}
export WEBUI_AUTH_COOKIE_SECURE=True        # 내부망이더라도 HTTPS면 True 권장 :contentReference[oaicite:6]{index=6}

# 6) 데이터 경로(영속)
export DATA_DIR="$HOME/.open-webui"         # 데이터 영속 경로 권장 설정 문서에 언급 :contentReference[oaicite:7]{index=7}

# (pip 실행)
open-webui serve --port 8080

참고: OFFLINE_MODE=True 로 두면 자동 업데이트 체크/임베딩 모델 자동 다운로드 등이 꺼지고, 오프라인에서도 오류 없이 동작하도록 보호해줘. 단, 외부 API·OAuth·웹검색 자체를 “기능적으로 막는” 스위치는 아니야. 네가 직접 끄거나 내부 리소스로만 연결해야 해. Open WebUI

(선택) 내부 검색/툴만 허용하고 싶다면

웹검색 완전 금지 : ENABLE_WEB_SEARCH=False 유지. Open WebUI

내부 SearXNG만 사용 : 자체 SearXNG를 세워서

export ENABLE_WEB_SEARCH=True
export WEB_SEARCH_ENGINE=searxng
export SEARXNG_QUERY_URL="http://searxng.internal/search?q=<query>&format=json"

처럼 내부 엔드포인트만 쓰게 해도 돼. Open WebUI

(선택) 내부 LLM 엔드포인트만 쓰기

OpenAI‑호환 서버(예: 사내 vLLM/LM Studio/프록시 등)를 Connections 에서 추가하면 돼. Base URL을 내부 주소로만 잡으면 외부로 못 나가. 가이드는 “OpenAI/호환 서버 시작하기”에 있어. Open WebUI+1

임베딩/Whisper 같은 모델은 “사전 캐시”

오프라인 모드에선 허깅페이스에서 자동 다운로드가 막히므로 , 모델 파일을 미리 받아서 Open WebUI 캐시 경로에 넣어둬야 해:

임베딩 모델: /app/backend/data/cache/embedding/models/
whisper: /app/backend/data/cache/whisper/models/
환경변수로 디폴트 모델도 지정 가능(RAG_EMBEDDING_MODEL, WHISPER_MODEL). Open WebUI

보안/운영 팁(필요한 것만)

첫 계정이 관리자 : 초기 셋업 때 만든 첫 계정이 Admin이라 사용자 승인/정책을 제어할 수 있어. Open WebUI
API 키 제어 : 필요하면 API Key Endpoint Restrictions 로 허용 엔드포인트를 제한할 수 있어(내부 API만 허용 목록으로). Open WebUI
PersistentConfig 주의 : ENABLE_SIGNUP, WEBUI_URL 등은 처음 값이 내부 DB에 저장 돼. 나중에 바꾸려면 Admin UI에서 수정하거나 ENABLE_PERSISTENT_CONFIG=False로 일시 해제 후 적용. Open WebUI
프록시가 있는 내부망 : 웹로더/웹검색이 내부 프록시만 통과하도록 http_proxy/https_proxy/no_proxy를 지원해. Open WebUI

체크리스트 (진짜 최소)

OFFLINE_MODE=True
WEBUI_URL을 내부 도메인으로 지정
ENABLE_SIGNUP=False 또는 기본 권한을 pending으로
ENABLE_WEB_SEARCH=False(또는 내부 SearXNG로 한정)
임베딩/Whisper 모델 사전 캐시 완료
DATA_DIR로 영속 경로 지정

원하면 네 환경 변수/내부 엔드포인트에 맞춘 한 줄 실행 스크립트(pip용)를 바로 만들어 줄게.

기본 포트 번호가 뭐야

pip로 설치해서 open-webui serve로 실행하면 기본 포트는 8080 이에요.

그래서 브라우저에서 http://localhost:8080으로 접속하면 됩니다.
포트를 바꾸고 싶으면:

open-webui serve --port 3000

처럼 --port 옵션을 주면 돼요.

endpoint로 모델 추가하는 법

오케이—엔드포인트를 이미 알고 있다는 전제로, Open WebUI에 모델(프로바이더) 추가 하는 가장 쉬운 방법을 빠르게 정리할게요. (pip 설치 기준, 폐쇄망도 OK)

1) UI에서 추가 (가장 간단)

브라우저에서 Open WebUI 접속 → Settings → Models → Providers
Add Provider 클릭 → 유형에서 OpenAI Compatible(또는 Ollama) 선택
입력:
- Base URL : 예) http://<host>:<port>/v1
- API Key : 엔드포인트 키 (필요 없으면 빈 값/토큰형식에 맞게)
- (옵션) Custom Headers : 사내 프록시/게이트웨이에서 헤더 요구 시 추가
Save → Refresh/Sync models(모델 목록 새로고침)
- 목록이 비면 “Model name ”을 직접 입력해 수동으로 추가(엔진이 노출하는 정확한 모델 ID 필요)
원하는 모델에 Set as default(기본 모델 지정)

vLLM/LM Studio/프록시류는 대부분 …/v1가 Base URL이고, 모델 ID는 서버가 가진 이름 그대로 써야 목록에 잘 뜹니다.

2) 환경변수로 미리 박아두고 실행 (초기 자동 설정)

# OpenAI-호환 엔드포인트 예시
export OPENAI_API_BASE_URL="http://<host>:<port>/v1"
export OPENAI_API_KEY="sk-xxxxxxxx"   # 필요 없으면 생략 가능
open-webui serve --port 8080

실행 후 Settings → Models 에 들어가면 위 값이 반영되어 있음.
여러 엔드포인트를 쓰려면 UI에서 프로바이더를 추가로 더 등록하세요.

3) (선택) Ollama 전용

UI에서 Ollama 유형 선택 후 Base URL : http://<host>:11434
또는

export OLLAMA_BASE_URL="http://<host>:11434"
open-webui serve

4) 연결 전 “엔드포인트 정상인지” 빠른 자가테스트

모델 목록 확인 (OpenAI 호환 표준)

curl -sS -H "Authorization: Bearer $OPENAI_API_KEY" \
  <BASE_URL>/models

200 OK + 모델 리스트가 나오면 OK.
에러면 Base URL 끝에/v1 누락, 키/헤더, CORS/프록시 등을 점검.

5) 흔한 이슈 & 바로 해결

모델이 안 뜸 :
- Base URL이 /v1인지 확인
- 내부망이면 모델 리스트 캐시 때문에 안 보일 수 → Settings에서 Refresh/Sync
- 그래도 안 뜨면 모델 ID 수동 입력(서버에서 쓰는 정확한 이름)
401/403 : 키 또는 커스텀 헤더 불일치. 게이트웨이가 요구하는 헤더를 Custom Headers 에 추가.
연결은 되는데 응답 에러 :
- 엔진이 OpenAI Chat Completions 스펙 지원하는지 확인(vLLM/LM Studio는 보통 지원)
- timeout 늘리기(서버가 느릴 때)
폐쇄망 : 외부 검색/다운로드가 필요 없게
- ENABLE_WEB_SEARCH=False, OFFLINE_MODE=True
- 임베딩/Whisper 모델은 미리 캐시(필요 시)

6) 최소 예시(가장 흔한 vLLM/LM Studio)

Base URL: http://10.0.0.5:8000/v1
API Key: (없으면 비움)
모델 ID: 서버가 노출하는 이름(예: Meta-Llama-3-8B-Instruct)
저장 → Refresh → 기본 모델로 지정

필요하면 당신이 가진 엔드포인트/모델ID/키 형식 에 맞춰서,
한 번에 붙는 환경변수 스니펫 이나 UI 입력값 표 를 맞춤으로 뽑아줄게.

모델 목록 새로고침은 어디있어?

Open WebUI에서 모델 목록 새로고침(Refresh/Sync) 버튼은 Settings → Models 화면에 있습니다.

정확히는 이렇게 찾으면 돼요:

브라우저에서 Open WebUI 접속
좌측 메뉴에서 ⚙ Settings 클릭
상단 탭 중에서 Models 선택
(여기서 이미 등록한 Provider들이 보입니다)
각 Provider 카드(예: "OpenAI Compatible") 오른쪽 위에 ⟳ 아이콘(또는 "Refresh"/"Sync Models" 버튼)이 있어요.
클릭하면 해당 엔드포인트에 /models 요청을 보내서 새로 모델 목록을 불러옵니다.

💡 참고:

새로고침 후에도 목록에 안 뜨면, 해당 엔드포인트가 /models 응답에 모델 ID를 반환하지 않는 경우일 수 있습니다.
이럴 땐 "Add model" 기능으로 모델 ID를 수동으로 넣어줘야 해요.
목록 캐시는 내부적으로 TTL이 있어서, 버튼 없이도 일정 시간 지나면 갱신되지만, 수동으로 바로 보고 싶으면 여기서 눌러주면 됩니다.

원하면 내가 UI 스크린샷처럼 생긴 구조를 그려서, Refresh 버튼이 정확히 어디 있는지 바로 보이게 해줄까요?
그러면 한 번에 찾을 수 있을 거예요.

이거 서버 꺼도 설정은 저장되지?

네, 서버 꺼도 설정은 저장됩니다.

Open WebUI는 설정(모델 엔드포인트, 사용자 계정, UI 환경설정 등)을 백엔드 데이터베이스 에 저장합니다.

pip 설치 시 기본 경로: ~/.open-webui (또는 --data-dir로 지정한 경로)
Docker 실행 시: /app/backend/data 볼륨

여기 안에는 SQLite DB(app.db), 캐시, 업로드 파일 등이 들어 있고,
서버를 꺼도 이 디렉터리만 유지되면 다음 실행 시 그대로 복원됩니다.

📌 주의할 점

Docker로 띄울 땐 볼륨 마운트 안 하면 컨테이너 삭제 시 데이터도 같이 날아갑니다.
ENABLE_PERSISTENT_CONFIG=True(기본값)일 때는 환경변수 값도 최초 기동 시점에 DB에 저장돼서, 이후 서버 재시작해도 DB 값이 우선됩니다.
설정 초기화하고 싶으면 --data-dir 새로 지정하거나 app.db만 지우면 됩니다.

원하면 내가 현재 Open WebUI가 설정 저장하는 경로를 확인하는 방법 도 알려줄게.
그러면 껐다 켜도 그대로 유지되는지 바로 테스트할 수 있어요.

아레나 모델은 뭐야?

아, “Arena Model(Arena 모드)”에 대해 물어보신 거군요! Open WebUI에서 제공하는 모델 평가 기능 으로, A/B 테스팅 을 쉽게 할 수 있는 모드입니다.

Arena Model이란?

여러 모델을 묶은 그룹 에서 무작위로 하나를 선택 해 응답을 생성하는 모드입니다. Open WebUI+10 GitHub
생성된 응답에는 어떤 모델이 썼는지 숨겨진 상태 여서, 블라인드 테스트 처럼 비교할 수 있어요.
내가 그 응답에 "좋아요/싫어요 "를 누르면, 어떤 모델이 썼는지 나중에 확인할 수 있고, 리더보드를 통해 모델 간 성능 순위 를 확인할 수 있습니다. Open WebUI GitHub

Arena Model 사용법 요약

Admin Panel → Settings → Evaluations 에서 Arena Model 그룹을 설정합니다.
평가에 포함할 모델들을 선택해 그룹에 추가합니다.
챗 화면에서 Arena Model 을 선택하면, 랜덤으로 모델이 하나 뽑혀 응답 생성.
응답에 좋아요/싫어요 클릭 → 뒤에 어떤 모델이 답했는지 확인 가능.
리더보드를 통해 각 모델의 비교 성능을 시각화할 수 있습니다. Open WebUI+5

왜 유용할까?

편견 없는 비교 : 사용자가 모델 이름을 몰라서 선입견 없이 평가 가능.
행동 기반 선호 : 좋아요/싫어요가 자동으로 더 좋은 모델을 띄워줌.
리더보드 제공 : 설정한 모델 그룹 내에서 어떤 모델이 강한지 한눈에 확인 가능.

필요하시면, 관리자 설정 화면 스크린샷 , 혹은 실제 Arena Model을 켜고 사용하는 예시 절차 스크립트까지 만들어드릴 수 있어요. 필요하신가요?