mirror of
https://github.com/open-webui/docs.git
synced 2026-01-04 10:46:26 +07:00
228 lines
4.1 KiB
Markdown
228 lines
4.1 KiB
Markdown
---
|
||
sidebar_position: 5
|
||
title: "🛠️ Development Guide"
|
||
---
|
||
|
||
import Tabs from '@theme/Tabs';
|
||
import TabItem from '@theme/TabItem';
|
||
import { TopBanners } from "@site/src/components/TopBanners";
|
||
|
||
<TopBanners />
|
||
|
||
# 🛠️ Development Setup Guide
|
||
|
||
Welcome to the **Open WebUI Development Setup Guide!** Whether you're a novice or an experienced developer, this guide will help you set up a **local development environment** for both the frontend and backend components. Let’s dive in! 🚀
|
||
|
||
## System Requirements
|
||
|
||
- **Operating System**: Linux (or WSL on Windows) or macOS
|
||
- **Python Version**: Python 3.11+
|
||
- **Node.js Version**: 20.10+
|
||
|
||
## Development Methods
|
||
|
||
<Tabs groupId="dev-setup">
|
||
|
||
<TabItem value="local" label="Local Setup">
|
||
|
||
### 🐧 Local Development Setup
|
||
|
||
1. **Clone the Repository**:
|
||
|
||
```bash
|
||
git clone https://github.com/open-webui/open-webui.git
|
||
cd open-webui
|
||
```
|
||
|
||
2. **Frontend Setup**:
|
||
- Create a `.env` file:
|
||
|
||
```bash
|
||
cp -RPp .env.example .env
|
||
```
|
||
|
||
- Install dependencies:
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
- Start the frontend server:
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
🌐 Available at: [http://localhost:5173](http://localhost:5173).
|
||
|
||
3. **Backend Setup**:
|
||
- Navigate to the backend:
|
||
|
||
```bash
|
||
cd backend
|
||
```
|
||
|
||
- Use **Conda** for environment setup:
|
||
|
||
```bash
|
||
conda create --name open-webui python=3.11
|
||
conda activate open-webui
|
||
```
|
||
|
||
- Install dependencies:
|
||
|
||
```bash
|
||
pip install -r requirements.txt -U
|
||
```
|
||
|
||
- Start the backend:
|
||
|
||
```bash
|
||
sh dev.sh
|
||
```
|
||
|
||
📄 API docs available at: [http://localhost:8080/docs](http://localhost:8080/docs).
|
||
|
||
</TabItem>
|
||
|
||
<TabItem value="docker" label="Docker Setup">
|
||
|
||
### 🐳 Docker-Based Development Setup
|
||
|
||
1. **Create the Docker Compose File**:
|
||
|
||
```yaml
|
||
name: open-webui-dev
|
||
|
||
services:
|
||
frontend:
|
||
build:
|
||
context: .
|
||
target: build
|
||
command: ["npm", "run", "dev"]
|
||
depends_on:
|
||
- backend
|
||
ports:
|
||
- "3000:5173"
|
||
extra_hosts:
|
||
- host.docker.internal:host-gateway
|
||
volumes:
|
||
- ./src:/app/src
|
||
|
||
backend:
|
||
build:
|
||
context: .
|
||
target: base
|
||
command: ["bash", "dev.sh"]
|
||
env_file: ".env"
|
||
environment:
|
||
- ENV=dev
|
||
- WEBUI_AUTH=False
|
||
ports:
|
||
- "8080:8080"
|
||
extra_hosts:
|
||
- host.docker.internal:host-gateway
|
||
volumes:
|
||
- ./backend:/app/backend
|
||
- data:/app/backend/data
|
||
|
||
volumes:
|
||
data: {}
|
||
```
|
||
|
||
2. **Start the Development Containers**:
|
||
|
||
```bash
|
||
docker compose -f compose-dev.yaml up --watch
|
||
```
|
||
|
||
3. **Stop the Containers**:
|
||
|
||
```bash
|
||
docker compose -f compose-dev.yaml down
|
||
```
|
||
|
||
</TabItem>
|
||
<TabItem value="conda" label="Optional Conda Setup">
|
||
|
||
### Conda Environment Setup
|
||
|
||
If you prefer using **Conda** for isolation:
|
||
|
||
1. **Create and Activate the Environment**:
|
||
|
||
```bash
|
||
conda create --name open-webui-dev python=3.11
|
||
conda activate open-webui-dev
|
||
```
|
||
|
||
2. **Install Dependencies**:
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
3. **Run the Servers**:
|
||
- Frontend:
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
- Backend:
|
||
|
||
```bash
|
||
sh dev.sh
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
<TabItem value="troubleshooting" label="Troubleshooting">
|
||
|
||
## 🐛 Troubleshooting
|
||
|
||
### **FATAL ERROR: Reached Heap Limit**
|
||
|
||
If you encounter memory-related errors during the build, increase the **Node.js heap size**:
|
||
|
||
1. **Modify Dockerfile**:
|
||
|
||
```dockerfile
|
||
ENV NODE_OPTIONS=--max-old-space-size=4096
|
||
```
|
||
|
||
2. **Allocate at least 4 GB of RAM** to Node.js.
|
||
|
||
---
|
||
|
||
### **Other Issues**
|
||
|
||
- **Port Conflicts**:
|
||
Ensure that no other processes are using **ports 8080 or 5173**.
|
||
|
||
- **Hot Reload Not Working**:
|
||
Verify that **watch mode** is enabled for both frontend and backend.
|
||
|
||
</TabItem>
|
||
|
||
</Tabs>
|
||
|
||
## Contributing to Open WebUI
|
||
|
||
### Local Workflow
|
||
|
||
1. **Commit Changes Regularly** to track progress.
|
||
2. **Sync with the Main Branch** to avoid conflicts:
|
||
|
||
```bash
|
||
git pull origin main
|
||
```
|
||
|
||
3. **Run Tests Before Pushing**:
|
||
|
||
```bash
|
||
npm run test
|
||
```
|
||
|
||
Happy coding! 🎉
|