Docker
Docker는 단일 서버에 프로덕션 방식으로 배포하는 가장 쉬운 방법입니다.
인터넷에서 접근 가능한 단일 서버 설치는 비공개 원격 배포에서 시작하세요. 해당 Compose 템플릿은 애플리케이션 포트를 공개하지 않고 기본적으로 main 이미지를 사용하며, 외부 Cloudflare Access 경계, 호스트 제어, 백업 및 컨테이너 제한을 추가합니다.
Work 사용 가능 여부
저장소 Compose 파일에서는 Work가 기본적으로 활성화됩니다. 이미지에 Docker CLI가 포함되어 있고 Compose가 /var/run/docker.sock을 마운트하므로 Work 작업 컨테이너는 Libre WebUI 컨테이너의 형제 컨테이너입니다. 호스트의 docker ps에 표시됩니다.
해당 소켓에 접근할 수 있는 프로세스는 Docker 호스트에 대해 root와 동등한 제어 권한을 갖습니다. Work를 기본적으로 활성화한 것은 의도적인 선택입니다. Work는 핵심 기능이며 데몬 접근 없이는 작동할 수 없습니다. 그 결과 모든 Libre WebUI 관리자는 사실상 호스트 관리자가 됩니다. 다음을 고려해 계획하세요.
- 이미 신뢰하는 관리자만 있는 호스트에서 스택을 실행합니다.
- 게시된 포트를 신뢰할 수 없는 네트워크에 노출하지 않습니다.
- Work가 필요하지 않으면
/var/run/docker.sock마운트를 제거합니다. 그러면 Work 페이지에 런타임을 사용할 수 없음이 표시됩니다.
Linux에서 소켓은 root가 아니라 docker 그룹에 속하므로 root가 아닌 앱 사용자에게 해당 그룹 ID가 필요합니다. 한 번 설정하세요.
echo "DOCKER_GID=$(docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
alpine stat -c '%g' /var/run/docker.sock)" >> .env
위와 같이 컨테이너를 통해 값을 읽으세요. Docker Desktop은 VM을 통해 소켓을 프록시하므로 macOS 호스트에서 보고하는 값은 컨테이너가 보는 값과 다릅니다. 그룹이 잘못된 경우 Work 페이지는 조용히 실패하지 않고 문제를 명시합니다. Work: 격리된 워크스페이스를 참조하세요.
Work 미리 보기와 Work Computer는 임의의 포트를 비공개 호스트 인터페이스에만 게시합니다. Docker Desktop에서는 Compose 기본값 그대로 동작합니다. 바인드 대상은 호스트 루프백이고, 백엔드 연결에는 host.docker.internal을 사용합니다. 네이티브 Docker Engine에서는 형제 컨테이너가 호스트 루프백의 리스너에 접근할 수 없습니다. 대신 공개되지 않은 Docker 브리지 게이트웨이를 바인드 대상으로 설정하세요.
echo "WORK_PREVIEW_BIND=$(docker network inspect bridge \
--format '{{(index .IPAM.Config 0).Gateway}}')" >> .env
echo "WORK_DOCKER_PUBLISHED_HOST=host.docker.internal" >> .env
docker compose up -d --force-recreate libre-webui
Compose 파일은 host-gateway를 통해 host.docker.internal을 매핑합니다. WORK_PREVIEW_BIND=0.0.0.0은 절대 사용하지 마세요. 인증되지 않은 임시 작업 포트가 Libre WebUI의 서명된 프록시 뒤에 남지 않고 모든 호스트 인터페이스에 게시됩니다.
번들 Ollama
Libre WebUI와 Ollama를 하나의 Compose 스택에서 실행합니다.
docker compose up -d
http://localhost:8080을 여세요.
WebUI 포트는 기본적으로 호스트 루프백에 바인딩됩니다. 신뢰할 수 있는 LAN이나 호스트 역방향 프록시가 접근해야 할 때만 WEBUI_BIND_ADDRESS=0.0.0.0을 설정하고 호스트 방화벽으로 포트를 제한하세요.
Ollama는 Compose 네트워크 내부에만 유지됩니다. 루프백에서 호스트 애플리케이션에 제공하려면 명시적인 호스트 오버라이드를 추가하세요.
docker compose -f docker-compose.yml -f docker-compose.ollama-host.yml up -d
다른 컴퓨터가 Ollama에 접근해야 할 때만 OLLAMA_BIND_ADDRESS를 설정하고, 방화벽과 인증을 지원하는 프록시로 해당 포트를 보호하세요.
NVIDIA GPU
Docker가 NVIDIA 런타임에 접근할 수 있을 때 GPU Compose 파일을 사용하세요.
docker compose -f docker-compose.gpu.yml up -d
모델이 여전히 CPU에서 실행된다면 Ollama 컨테이너의 GPU 접근을 확인하세요.
외부 Ollama
Ollama가 이미 호스트나 다른 서버에서 실행 중일 때 사용합니다.
docker compose -f docker-compose.external-ollama.yml up -d
필요하면 Ollama URL을 재정의하세요.
OLLAMA_BASE_URL=http://192.168.1.10:11434 docker compose -f docker-compose.external-ollama.yml up -d
소켓이 격리된 Work
표준 Compose 파일은 Work에서 작업 컨테이너를 실행할 수 있도록 Docker 소켓을 Libre WebUI 컨테이너에 마운트합니다. 이 마운트는 Docker 호스트에 대해 root와 동등한 제어 권한을 제공합니다. 웹 애플리케이션에 소켓을 주지 않으면서 Work를 유지하려면 socket-proxy 변형을 사용하세요.
docker compose -f docker-compose.socket-proxy.yml up -d
내부 네트워크의 소켓 프록시가 /var/run/docker.sock을 보유하고 Work가 사용하는 API 영역(컨테이너, 이미지, 볼륨, 네트워크, exec, info)만 전달합니다. Swarm, secrets, configs, build 및 system 엔드포인트는 프록시에서 거부됩니다. Libre WebUI는 DOCKER_HOST=tcp://docker-socket-proxy:2375를 통해 접근합니다. 소켓 마운트와 DOCKER_GID가 필요 없으며 대화형 터미널과 시스템 진단은 그대로 작동합니다. 이 경계가 보장하는 범위와 보장하지 않는 범위는 워크스페이스 문서를 참조하세요.
데이터 영속성
Libre WebUI는 컨테이너 내부의 /app/backend/data에 백엔드 데이터를 저장합니다. Compose 파일은 해당 경로를 명명 볼륨으로 마운트합니다.
이미지를 docker run으로 직접 실행할 때도 기본적으로 이 경로를 사용하며, 데이터베이스 사전 점검 임시 데이터는 /app/backend/temp에 별도로 보관합니다. 컨테이너를 다시 만들 가능성이 있다면 /app/backend/data를 마운트하세요.
프로덕션에서는 안정적인 비밀 값을 설정하세요.
JWT_SECRET=replace-with-a-long-random-secret
ENCRYPTION_KEY=replace-with-64-hex-characters
데이터 볼륨과 암호화 키를 함께 백업하세요.
이전 이미지로 직접 실행해 만든 컨테이너를 제거하기 전에 /app/backend/data/.encryption_key가 존재하는지 확인하거나 설정된 ENCRYPTION_KEY를 기록하세요. 이전 이미지는 자동 생성된 키를 컨테이너 계층에만 기록할 수 있었습니다. 해당 컨테이너를 삭제하면 영속 데이터베이스를 복호화할 유일한 키도 삭제됩니다.
사용자 지정 Work 지원 런타임을 운영하는 경우 작업 파일은 별도의 Docker 명명 볼륨에 있으며 일반 /app/backend/data 백업에 포함되지 않습니다.
공개 접근
저장소 Compose 파일은 WebUI를 루프백에 바인딩하고 CORS_ORIGIN을 직접 설정합니다. 셸이나 .env 파일의 값은 해당 리터럴을 대체하지 않습니다. libre-webui.environment 항목을 편집하거나 명시적인 오버라이드를 compose.origin.yml로 저장하세요.
services:
libre-webui:
environment:
CORS_ORIGIN: https://your-domain.example
BASE_URL: https://your-domain.example
선택한 저장소 Compose 파일과 함께 오버라이드를 적용하세요.
docker compose -f docker-compose.yml -f compose.origin.yml up -d
그런 다음 HTTPS를 사용하는 역방향 프록시나 플랫폼 로드 밸런서 뒤에 Libre WebUI를 배치하세요. WEBUI_BIND_ADDRESS는 프록시에 필요한 정확한 인터페이스로 설정합니다. 방화벽 구성상 반드시 필요한 경우가 아니면 모든 인터페이스에 포트를 게시하지 마세요.
서버는 이미 빌드된 프런트엔드를 효율적으로 전달합니다. /js/와 /assets/ 아래의 해시가 붙은 번들은 brotli 또는 gzip으로 압축되어 1년짜리 immutable 캐시 수명과 함께 전송되고, index.html과 서비스 워커는 no-cache로 표시되므로 새 릴리스가 다음 로드에서 적용됩니다. 프록시가 이런 경로를 다시 압축하거나 캐시할 필요는 없습니다. Accept-Encoding은 그대로 전달하세요.
유용한 명령
docker compose ps
docker compose logs -f libre-webui
docker compose logs -f ollama
docker compose pull
docker compose up -d