본문으로 건너뛰기

🧪 개발 브랜치 가이드

공식 출시 전에 최신 기능을 사용해 보고 싶으신가요? 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

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 브라우저 스위트를 검사합니다. 실패한 브라우저 실행은 디버깅을 위해 Playwright 결과를 업로드합니다.

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