🛠️ Development Guide

System Requirements

Before diving into the setup, make sure your system meets the following requirements:

Operating System: Linux (WSL) or macOS (Instructions provided here specifically cater to these operating systems)
Python Version: Python 3.11

🐧 Linux/macOS Setup Guide

This section provides a step-by-step process to get your development environment ready on Linux (WSL) or macOS platforms.

📡 Cloning the Repository

First, you'll need to clone the Open WebUI repository and switch to the directory:

git clone https://github.com/open-webui/open-webui.git
cd open-webui

🖥️ Frontend Server Setup

To set up the frontend server, follow these instructions:

Environment Configuration: Duplicate the environment configuration file:
```
cp -RPp .env.example .env
```
Install Dependencies: Run the following commands to install necessary dependencies:
```
npm install
```
Launch the Server: Start the server with:
```
npm run dev
```
🌐 The frontend server will be available at: http://localhost:5173. Please note that for the frontend server to function correctly, the backend server should be running concurrently.

🖥️ Backend Server Setup

Setting up the backend server involves a few more steps, Python 3.11 is required for Open WebUI:

Change Directory: Open a new terminal window and navigate to the backend directory:
```
cd open-webui/backend
```
Python Environment Setup (Using Conda Recommended):
- Create and activate a Conda environment with Python 3.11:
```
conda create --name open-webui python=3.11
conda activate open-webui
```
Install Backend Dependencies: Install all the required Python libraries:
```
pip install -r requirements.txt -U
```
Start the Backend Application: Launch the backend application with:
```
sh dev.sh
```
📄 Access the backend API documentation at: http://localhost:8080/docs. The backend supports hot reloading, making your development process smoother by automatically reflecting changes.

That's it! You now have both the frontend and backend servers running. Explore the API documentation and start developing features for Open WebUI. Happy coding! 🎉

🐳 Running in a Docker Container

For those who prefer using Docker, here's how you can set things up:

Initialize Configuration: Assuming you have already cloned the repository and created a .env file, create a new file named compose-dev.yaml. This configuration uses Docker Compose to ease the development setup.

name: open-webui-dev

services:
  frontend:
    build:
      context: .
      target: build
    command: ["npm", "run", "dev"]
    depends_on:
      - backend
    extra_hosts:
      - host.docker.internal:host-gateway
    ports:
      - "3000:5173"
    develop:
      watch:
        path: ./src
        action: sync

  backend:
    build:
      context: .
      target: base
    command: ["bash", "dev.sh"]
    env_file: ".env"
    environment:
      - ENV=dev
      - WEBUI_AUTH=False
    volumes:
      - data:/app/backend/data
    extra_hosts:
      - host.docker.internal:host-gateway
    ports:
      - "8080:8080"
    restart: always
    develop:
      watch:
        path: ./backend
        action: sync

volumes:
  data: {}

Start Development Containers:

docker compose -f compose-dev.yaml up --watch

This command will start the frontend and backend servers in hot reload mode. Changes in your source files will trigger an automatic refresh. The web app will be available at http://localhost:3000 and Backend API docs at http://localhost:8080/docs.

Stopping the Containers:

To stop the containers, you can use:

docker compose -f compose-dev.yaml down

🔄 Integration with Pipelines

If your development involves Pipelines, you can enhance your Docker setup:

services:
  pipelines:
    ports:
      - "9099:9099"
    volumes:
      - ./pipelines:/app/pipelines
    extra_hosts:
      - host.docker.internal:host-gateway
    restart: always

This setup involves mounting the pipelines directory to ensure any changes reflect immediately, maintaining high development agility.

note

This configuration uses volume bind-mounts. Learn more about how they differ from named volumes here.

🐛 Troubleshooting

FATAL ERROR: Reached heap limit

When you encounter a memory-related error during the Docker build process—especially while executing npm run build—it typically indicates that the JavaScript heap has exceeded its memory limit. One effective solution is to increase the memory allocated to Node.js by adjusting the NODE_OPTIONS environment variable. This allows you to set a higher maximum heap size, which can help prevent out-of-memory errors during the build process. If you encounter this issue, try to allocate at least 4 GB of RAM, or higher if you have enough RAM.

You can increase the memory allocated to Node.js by adding the following line just before npm run build in the Dockerfile.

ENV NODE_OPTIONS=--max-old-space-size=4096

Through these setup steps, both new and experienced contributors can seamlessly integrate into the development workflow of Open WebUI. Happy coding! 🎉

System Requirements​

🐧 Linux/macOS Setup Guide​

📡 Cloning the Repository​

🖥️ Frontend Server Setup​

🖥️ Backend Server Setup​

🐳 Running in a Docker Container​

🔄 Integration with Pipelines​

🐛 Troubleshooting​

FATAL ERROR: Reached heap limit​