Skip to content

MACOS_SETUP_ISSUES.md

Latest commit

 

History

History
182 lines (133 loc) · 4.66 KB

MACOS_SETUP_ISSUES.md

File metadata and controls

182 lines (133 loc) · 4.66 KB

macOS Setup Guide for LangBuilder

When you clone LangBuilder from GitHub onto a Mac, there are several issues you'll encounter that need to be fixed before the platform will run. This guide walks through exactly what needs to be done.

Prerequisites

Install these first:

# Python 3.11 (required - Python 3.13 is NOT compatible with OpenWebUI)
brew install python@3.11

# Node.js
brew install node

# uv package manager
curl -LsSf https://astral.sh/uv/install.sh | sh

Step 1: Clone and Configure

git clone https://github.com/CloudGeometry/LangBuilder.git
cd LangBuilder

# Create your .env file
cp .env.example .env
# Edit .env with your API keys, OAuth credentials, etc.

Step 2: Fix OpenWebUI Code Bug (ALREADY FIXED)

Note: This bug has been fixed in the current codebase. The line already exists at openwebui/backend/open_webui/env.py line 114. You can skip this step.

Problem: The backend won't start because WEBUI_NAME is imported but never defined.

Fix: Edit openwebui/backend/open_webui/env.py and add this line around line 114 (near WEBUI_FAVICON_URL):

WEBUI_NAME = os.environ.get("WEBUI_NAME", "Open WebUI")

Step 3: Setup OpenWebUI

cd openwebui

# Create virtual environment with Python 3.11 specifically
python3.11 -m venv .venv

# Install backend dependencies
.venv/bin/pip install -r backend/requirements.txt

# Install frontend dependencies
npm install --legacy-peer-deps

# Install missing y-protocols package (required for TipTap editor)
npm install y-protocols --legacy-peer-deps

cd ..

Step 4: Setup LangBuilder

cd langbuilder

# Create virtual environment
uv venv

# Install dependencies
make install_backend
make install_frontend

Critical: Create the local .env file. Vite reads from langbuilder/.env, not the root .env:

cat > .env << 'EOF'
# LangBuilder Frontend Configuration
VITE_PROXY_TARGET=http://localhost:8002
VITE_PORT=3000
EOF
cd ..

Step 5: Handle Database Migration (if needed)

If you see this error when starting:

sqlite3.OperationalError: table publish_record already exists

Fix it by stamping the migration:

cd langbuilder
uv run alembic stamp head
cd ..

Or delete the database for a fresh start:

rm langbuilder/src/backend/base/langbuilder/langbuilder.db

Step 6: Start Everything

./start_all_macos.sh

The script will run pre-flight checks and tell you if anything is missing.

Service URLs

Service URL
OpenWebUI Frontend http://localhost:5175
OpenWebUI Backend http://localhost:8767
LangBuilder Frontend http://localhost:3000
LangBuilder Backend http://localhost:8002

Summary of Fixes Required

What Why Fix
Use Python 3.11 Python 3.13 breaks OpenWebUI dependencies brew install python@3.11
Add WEBUI_NAME to env.py Code bug - variable imported but not defined ALREADY FIXED in codebase
Install y-protocols Missing npm dependency for TipTap editor npm install y-protocols --legacy-peer-deps
Create langbuilder/.env Vite reads wrong .env file, proxy fails Create file with VITE_PROXY_TARGET
Fix .env port references ${BACKEND_PORT} not evaluated by scripts Change to literal 8767
Use macOS startup scripts Original scripts have Windows paths Use start_all_macos.sh

Troubleshooting

"Cannot import WEBUI_NAME"

This bug has been fixed in the codebase. If you still see this error, ensure you have the latest code.

"Invalid value for '--port': '${BACKEND_PORT}' is not a valid integer"

The .env file uses variable references that the startup scripts cannot evaluate:

# Change this in .env:
OPEN_WEBUI_PORT=${BACKEND_PORT}  # Wrong - won't work
PORT=${BACKEND_PORT}              # Wrong - won't work

# To this:
OPEN_WEBUI_PORT=8767              # Correct
PORT=8767                         # Correct

"Could not resolve y-protocols/awareness"

You forgot to install y-protocols:

cd openwebui && npm install y-protocols --legacy-peer-deps

Vite proxy returns 500 errors / ECONNREFUSED

The langbuilder/.env file is missing or doesn't have VITE_PROXY_TARGET:

echo "VITE_PROXY_TARGET=http://localhost:8002" > langbuilder/.env

"table publish_record already exists"

cd langbuilder && uv run alembic stamp head

Port already in use

# Find and kill the process
lsof -ti:8002 | xargs kill -9  # LangBuilder backend
lsof -ti:3000 | xargs kill -9  # LangBuilder frontend
lsof -ti:8767 | xargs kill -9  # OpenWebUI backend
lsof -ti:5175 | xargs kill -9  # OpenWebUI frontend