본문으로 건너뛰기

🧪 개발 브랜치 가이드

공식 출시 전에 최신 기능을 사용해 보고 싶으신가요? dev 브랜치에는 최종적으로 메인 릴리스에 포함될 최첨단 개선 사항과 실험적 기능이 들어 있습니다.

실험적 소프트웨어

dev 브랜치는 실험적이며 버그, 미완성 기능 또는 호환성을 깨뜨리는 변경 사항이 포함될 수 있습니다. 잠재적인 불안정성을 감수할 수 있고 Libre WebUI 개선을 돕고 싶을 때만 사용하세요.

🎯 Dev 브랜치란?​

개발 브랜치(dev)는 새 기능을 안정적인 main 브랜치에 병합하기 전에 테스트하는 곳입니다. 다음이 포함됩니다.

  • 안정 릴리스에 아직 없는 최신 기능
  • 테스트 중인 버그 수정
  • UI와 기능의 실험적 개선 사항
  • 개발 중인 성능 최적화

🚀 Dev 브랜치 사용 방법​

Docker 설정(권장)​

개발용 Compose 파일은 호스트 Docker 소켓을 마운트하므로 Docker를 사용할 수 있을 때 Work가 기본적으로 작동합니다. 작업 컨테이너는 호스트 데몬에서 실행되고 docker ps에 표시됩니다. Linux에서는 먼저 .env에 DOCKER_GID를 설정하세요.

외부 Ollama 사용:

# Clone the repository
git clone https://github.com/libre-webui/libre-webui.git
cd libre-webui

# Switch to dev branch
git checkout dev

# Start the dev image with external Ollama
docker compose -f docker-compose.dev.external-ollama.yml up -d

간단한 Docker 실행:

# Use the dev branch image
docker run -d -p 3000:3001 -v libre-webui:/app/backend/data --name libre-webui-dev --restart always ghcr.io/libre-webui/libre-webui:dev

소스에서 실행​

# Clone and switch to dev branch
git clone https://github.com/libre-webui/libre-webui.git
cd libre-webui
git checkout dev

# Install dependencies
npm install

# Start development server
npm run dev

백엔드가 시작 점검을 마치기 전에 Vite가 먼저 준비될 수 있습니다. 로컬 백엔드의 경우 개발 프록시는 API 요청을 전달하기 전에 리스너가 열릴 때까지 최대 10초 기다립니다. 쓰기 요청을 포함해 각 요청은 한 번만 전달하며 실패한 요청을 다시 보내지 않습니다. 백엔드를 계속 사용할 수 없으면 프록시는 재시도 안내와 함께 HTTP 503을 반환합니다. 기다리는 동안에도 프런트엔드 정적 파일은 계속 제공됩니다.

채팅은 백엔드가 일시적으로 중단된 뒤에도 계속 다시 연결하며 대기 시간은 최대 30초입니다. 연결에 성공하면 대기 시간이 초기화되고, 로그아웃하면 대기 중인 재시도가 취소됩니다. 인증 실패 시에는 자동 재연결을 중단합니다.

Work 테스트​

  1. Docker를 시작하고 백엔드를 실행하는 동일한 사용자로 docker info가 성공하는지 확인합니다.
  2. npm run dev를 사용해 소스에서 Libre WebUI를 시작합니다.
  3. 관리자로 로그인합니다.
  4. Work를 선택하고 도구를 지원하는 Ollama, Ollama Cloud 또는 설정된 플러그인 기반 모델을 사용합니다.

다음 명령으로 백엔드 제공자 및 컨테이너 정책 집중 테스트를 실행하세요.

npm run test:work

테스트는 생성된 Docker 정책, 경로 제한, 수명 주기와 용량 동작 및 OpenAI 호환, Anthropic, Gemini 도구 어댑터를 검증합니다. 전체 런타임 경계는 Work: 격리된 워크스페이스를 참조하세요.

🔄 최신 상태 유지하기​

Dev 브랜치는 자주 업데이트됩니다. 최신 변경 사항을 가져오려면 다음을 실행하세요.

# Update your local dev branch
git pull origin dev

# Refresh the dev Compose stack
docker compose -f docker-compose.dev.external-ollama.yml pull
docker compose -f docker-compose.dev.external-ollama.yml up -d

# Or restart simple Docker
docker pull ghcr.io/libre-webui/libre-webui:dev
docker stop libre-webui-dev && docker rm libre-webui-dev
docker run -d -p 3000:3001 -v libre-webui:/app/backend/data --name libre-webui-dev --restart always ghcr.io/libre-webui/libre-webui:dev

🐛 버그를 발견하셨나요? 개선을 도와주세요!​

버그 보고는 매우 소중합니다. 효과적으로 문제를 보고하는 방법은 다음과 같습니다.

보고하기 전에​

  1. 기존 이슈 확인: 중복을 피하려면 GitHub Issues를 검색하세요.
  2. 안정 버전 시도: 버그가 main 브랜치가 아니라 dev에만 있는지 확인하세요.
  3. 일관되게 재현: 버그를 다시 발생시킬 수 있는지 확인하세요.

버그 보고 방법​

🐛 GitHub에서 버그 보고

다음 정보를 포함하세요:

**Environment:**

- Branch: dev
- Version: [git commit hash or date]
- OS: [Windows/macOS/Linux]
- Browser: [Chrome/Firefox/Safari version]
- Setup: [Docker/Source/etc.]
- Docker: [version and whether `docker info` succeeds, for Work issues]
- Work model/provider: [exact route, when applicable]

**Bug Description:**
Clear description of what went wrong

**Steps to Reproduce:**

1. Go to...
2. Click on...
3. See error...

**Expected Behavior:**
What should have happened

**Actual Behavior:**
What actually happened

**Screenshots/Logs:**
[If applicable, add screenshots or error logs]

**Work Activity:**
[Relevant tool call/result or preview output, with secrets removed]

Git 커밋 해시 확인​

# Find your current dev branch commit
git rev-parse HEAD

# Or get a short version
git rev-parse --short HEAD

🏆 기여 및 인정​

Dev 브랜치를 사용하면 테스트 커뮤니티의 일원이 됩니다. 기여자는 여러 방식으로 인정받습니다.

기여자 인정​

  • CONTRIBUTORS.md에 등록
  • 중요한 기여는 릴리스 노트에 언급
  • 커밋 메시지의 공동 작성자 표기
  • 프로젝트 공지의 특별 감사

현재 기여자​

멋진 커뮤니티 구성원은 다음과 같습니다.

  • rob - 프로젝트 관리자
  • jm - 네트워크 접근 개선
  • 그 밖의 많은 기여자! 전체 목록을 확인하세요.

코드에 기여하고 싶으신가요?​

  1. 저장소를 포크합니다.
  2. dev에서 기능 브랜치를 만듭니다: git checkout -b feature/amazing-feature dev
  3. 변경 사항을 작성합니다.
  4. dev 브랜치를 대상으로 Pull Request를 제출합니다.

자세한 지침은 기여 가이드를, 프로젝트의 윤리 지침과 거버넌스 모델은 커뮤니티 헌장을 참조하세요.

Pull Request 검사​

중간 기능 또는 수정 브랜치를 대상으로 하는 스택형 Pull Request를 포함한 모든 Pull Request는 Format & Lint 워크플로를 실행합니다. 독립 작업이 서식, 프런트엔드 및 백엔드 린트, TypeScript 유형, 패키지 및 회귀 테스트, Playwright 브라우저 스위트를 검사합니다. Chromium은 전체 브라우저 스위트를 실행합니다. WebKit과 Firefox도 핵심 흐름인 인증, 스트리밍, 대화 상자, 탭, 자동화, 저장소, Work, 음성 재생을 실행합니다. 각 엔진은 자체 CI 작업에서 실행되며, 실패한 실행은 테스트 결과를 따로 업로드합니다.

테스트를 거친 npm tarball은 Linux, macOS, Windows에서 Node 22.22와 Node 24를 모두 사용해 새 소비자 디렉터리에 설치됩니다. 이 검사는 체크아웃의 node_modules를 빌려 쓰지 않고 실제 프로덕션 의존성을 설치한 다음, CLI 시작, 준비 상태, 프런트엔드 제공, 재시작 전후의 데이터를 확인합니다. 같은 검사를 로컬에서 실행하려면 npm run build 후에 npm run test:package-install을 실행하세요. 특정 아티팩트를 테스트하려면 tarball 또는 tarball 하나가 들어 있는 디렉터리를 전달합니다. 깨끗한 설치에는 레지스트리 접근이 필요하며, 미리 빌드된 의존성을 사용할 수 없을 때는 플랫폼의 일반적인 네이티브 모듈 빌드 요구 사항도 필요합니다.

별도의 Work Computer 작업은 런타임에 고정된 베이스에서 GUI 이미지를 빌드하고 실제 상호 작용 회귀 테스트를 실행합니다. TEST_WORK_COMPUTER=1을 설정하면 Docker 데몬이나 이미지가 없을 때 검사를 건너뛰지 않고 실패로 처리합니다. 로컬에서 재현하려면 이 플래그를 설정하고 WORK_COMPUTER_TEST_IMAGE를 별도로 빌드한 테스트 이미지로 지정한 다음 npm run test:work-computer를 실행하세요. 필수 모드가 아니면 선택 사항인 GUI 픽스처가 없을 때 로컬 실행은 여전히 건너뜀으로 보고합니다.

이 매트릭스는 지원되는 환경에 대한 검사를 추가할 뿐이며, 지원되지 않는 조합을 활성화하지는 않습니다. 노드 로컬 CLI 자격 증명은 여전히 외부 팀 워커에서 사용할 수 없습니다.

CodeQL은 모든 Pull Request에서 JavaScript/TypeScript, Python, 워크플로 코드를 검사합니다. examples/ 아래의 실행 가능한 Python 제공자 서버는 .gitattributes에서 명시적으로 코드로 분류되어 있으므로 GitHub 언어 감지에 포함됩니다. 별도로 관리되는 Code Quality 설정에는 JavaScript/TypeScript와 Python이 모두 포함되어야 합니다. 수정한 뒤에도 이전 결과가 남아 있으면 분석된 리비전과 언어 범위를 확인하고, 변경 사항을 게시한 뒤 해당 분석을 새로 고치세요. 표시되는 등급을 올리려는 목적만으로 유효한 결과를 무시하거나 올바른 비동기 동작을 바꾸지 마세요.

Electron Dev Build 워크플로는 macOS, Windows 및 Linux Artifacts도 패키징합니다. macOS Pull Request 빌드는 업로드 전에 패키징된 애플리케이션을 검증할 수 있도록 프로젝트의 자격 증명 없는 임시 서명을 유지합니다. Pull Request 워크플로에는 Developer ID 또는 공증 자격 증명이 제공되지 않습니다.

Docker Build Test and Push 워크플로는 중간 브랜치를 대상으로 하는 스택형 Pull Request를 포함해 모든 Pull Request의 amd64 및 arm64 이미지를 빌드합니다. Pull Request 빌드는 컨테이너 레지스트리에 로그인하거나 이미지 다이제스트를 푸시하거나 다중 아키텍처 매니페스트를 게시하지 않습니다.

Pull Request를 열기 전에 동일한 애플리케이션 수준 검사를 로컬에서 실행하세요.

npm run format:check
npm run lint
npm run test:package
npm run test:e2e

⚠️ 중요 참고 사항​

데이터 안전​

  • Dev 브랜치로 전환하기 전에 데이터를 백업하세요.
  • Work 작업 파일은 별도의 libre-work-* Docker 명명 볼륨에 있습니다. 파괴적인 작업 또는 사용자 수명 주기 변경을 테스트하기 전에 SQLite 데이터 디렉터리와 별도로 백업하세요.
  • Dev 테스트에는 별도의 Docker 볼륨을 사용하세요. 
    # Use different volume name for dev
    docker run -d -p 3000:3001 -v libre-webui-dev:/app/backend/data --name libre-webui-dev ghcr.io/libre-webui/libre-webui:dev

잠재적 문제​

  • 호환성을 깨뜨리는 변경으로 설정 업데이트가 필요할 수 있습니다.
  • 기능이 미완성이거나 예고 없이 바뀔 수 있습니다.
  • 최적화를 테스트하는 동안 성능이 달라질 수 있습니다.
  • UI 요소의 모양이나 동작이 달라질 수 있습니다.

안정 버전을 사용해야 할 때​

다음에 해당하면 안정적인 main 브랜치로 돌아가세요.

  • 중요한 작업에 안정성이 필요한 경우
  • 버그가 너무 많이 발생하는 경우
  • 테스트된 안정적 경험을 원하는 경우
# Switch back to stable
git checkout main
docker compose -f docker-compose.external-ollama.yml pull
docker compose -f docker-compose.external-ollama.yml up -d

🌟 커뮤니티 참여하기​

Libre WebUI의 미래를 함께 만들어 갈 준비가 되셨나요? 🚀

Dev 브랜치에서의 테스트, 피드백 및 기여는 모든 사용자의 경험을 직접 개선합니다. 개발 커뮤니티의 일원이 되어 주셔서 감사합니다!