π οΈ 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β
- Local Setup
- Docker Setup
- Optional Conda Setup
- Troubleshooting
π§ Local Development Setupβ
-
Clone the Repository:
git clone https://github.com/open-webui/open-webui.git
cd open-webui -
Frontend Setup:
- Create a
.env
file:cp -RPp .env.example .env
- Install dependencies:
npm install
- Start the frontend server:
π Available at: http://localhost:5173.
npm run dev
- Create a
-
Backend Setup:
- Navigate to the backend:
cd backend
- Use Conda for environment setup:
conda create --name open-webui python=3.11
conda activate open-webui - Install dependencies:
pip install -r requirements.txt -U
- Start the backend:
π API docs available at: http://localhost:8080/docs.
sh dev.sh
- Navigate to the backend:
π³ Docker-Based Development Setupβ
-
Create the Docker Compose File:
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: {} -
Start the Development Containers:
docker compose -f compose-dev.yaml up --watch
-
Stop the Containers:
docker compose -f compose-dev.yaml down
Conda Environment Setupβ
If you prefer using Conda for isolation:
-
Create and Activate the Environment:
conda create --name open-webui-dev python=3.11
conda activate open-webui-dev -
Install Dependencies:
pip install -r requirements.txt
-
Run the Servers:
- Frontend:
npm run dev
- Backend:
sh dev.sh
- Frontend:
π Troubleshootingβ
FATAL ERROR: Reached Heap Limitβ
If you encounter memory-related errors during the build, increase the Node.js heap size:
-
Modify Dockerfile:
ENV NODE_OPTIONS=--max-old-space-size=4096
-
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.
Contributing to Open WebUIβ
Local Workflowβ
-
Commit Changes Regularly to track progress.
-
Sync with the Main Branch to avoid conflicts:
git pull origin main
-
Run Tests Before Pushing:
npm run test
Happy coding! π