diff --git a/README.md b/README.md index 189e5b6..b7850bc 100644 --- a/README.md +++ b/README.md @@ -111,42 +111,141 @@ Learn more about our project at [https://www.open-notebook.ai](https://www.open- Both registries contain identical images - choose whichever you prefer! -Ready to try Open Notebook? Choose your preferred method: +### Choose Your Setup: + + + + + + +
+ +#### 🏠 **Local Machine Setup** +Perfect if Docker runs on the **same computer** where you'll access Open Notebook. -### ⚡ Instant Setup (Recommended) ```bash -# Create a new directory for your Open Notebook installation -mkdir open-notebook -cd open-notebook +mkdir open-notebook && cd open-notebook -# Using Docker - Get started in 2 minutes docker run -d \ --name open-notebook \ -p 8502:8502 -p 5055:5055 \ -v ./notebook_data:/app/data \ -v ./surreal_data:/mydata \ - -e OPENAI_API_KEY=your_key \ + -e OPENAI_API_KEY=your_key_here \ lfnovo/open_notebook:v1-latest-single - -# Or use GitHub Container Registry: -# ghcr.io/lfnovo/open-notebook:v1-latest-single ``` +**Access at:** http://localhost:8502 + + + +#### 🌐 **Remote Server Setup** +Use this for servers, Raspberry Pi, NAS, Proxmox, or any remote machine. + +```bash +mkdir open-notebook && cd open-notebook + +docker run -d \ + --name open-notebook \ + -p 8502:8502 -p 5055:5055 \ + -v ./notebook_data:/app/data \ + -v ./surreal_data:/mydata \ + -e OPENAI_API_KEY=your_key_here \ + -e API_URL=http://YOUR_SERVER_IP:5055 \ + lfnovo/open_notebook:v1-latest-single +``` + +**Replace `YOUR_SERVER_IP`** with your server's IP (e.g., `192.168.1.100`) or domain + +**Access at:** http://YOUR_SERVER_IP:8502 + +
+ +> **⚠️ Critical Setup Notes:** +> +> **Both ports are required:** +> - **Port 8502**: Web interface (what you see in your browser) +> - **Port 5055**: API backend (required for the app to function) +> +> **API_URL must match how YOU access the server:** +> - ✅ Access via `http://192.168.1.100:8502` → set `API_URL=http://192.168.1.100:5055` +> - ✅ Access via `http://myserver.local:8502` → set `API_URL=http://myserver.local:5055` +> - ❌ Don't use `localhost` for remote servers - it won't work from other devices! + +### Using Docker Compose (Recommended for Easy Management) + +Create a `docker-compose.yml` file: + +```yaml +services: + open_notebook: + image: lfnovo/open_notebook:v1-latest-single + # Or use: ghcr.io/lfnovo/open-notebook:v1-latest-single + ports: + - "8502:8502" # Web UI + - "5055:5055" # API (required!) + environment: + - OPENAI_API_KEY=your_key_here + # For remote access, uncomment and set your server IP/domain: + # - API_URL=http://192.168.1.100:5055 + volumes: + - ./notebook_data:/app/data + - ./surreal_data:/mydata + restart: always +``` + +Start with: `docker compose up -d` + **What gets created:** ``` open-notebook/ +├── docker-compose.yml # Your configuration ├── notebook_data/ # Your notebooks and research content └── surreal_data/ # Database files ``` -**Access your installation:** -- **🖥️ Main Interface**: http://localhost:8502 (Next.js UI) -- **🔧 API Access**: http://localhost:5055 (REST API) -- **📚 API Documentation**: http://localhost:5055/docs (Interactive Swagger UI) +### 🆘 Quick Troubleshooting -> **⚠️ Important**: -> 1. **Run from a dedicated folder**: Create and run this from inside a new `open-notebook` folder so your data volumes are properly organized -> 2. **Volume persistence**: The volumes (`-v ./notebook_data:/app/data` and `-v ./surreal_data:/mydata`) are essential to persist your data between container restarts. Without them, you'll lose all your notebooks and research when the container stops. +| Problem | Solution | +|---------|----------| +| **"Unable to connect to server"** | Set `API_URL` environment variable to match how you access the server (see remote setup above) | +| **Blank page or errors** | Ensure BOTH ports (8502 and 5055) are exposed in your docker command | +| **Works on server but not from other computers** | Don't use `localhost` in `API_URL` - use your server's actual IP address | +| **"404" or "config endpoint" errors** | Don't add `/api` to `API_URL` - use just `http://your-ip:5055` | +| **Still having issues?** | Check our [5-minute troubleshooting guide](docs/troubleshooting/quick-fixes.md) or [join Discord](https://discord.gg/37XJPXfz2w) | + +### How Open Notebook Works + +``` +┌─────────────────────────────────────────────────────────┐ +│ Your Browser │ +│ Access: http://your-server-ip:8502 │ +└────────────────┬────────────────────────────────────────┘ + │ + ▼ + ┌───────────────┐ + │ Port 8502 │ ← Next.js Frontend (what you see) + │ Frontend │ + └───────┬───────┘ + │ needs to call ↓ + ▼ + ┌───────────────┐ + │ Port 5055 │ ← FastAPI Backend (handles requests) + │ API │ This is why you need API_URL! + └───────┬───────┘ + │ + ▼ + ┌───────────────┐ + │ SurrealDB │ ← Database (internal, auto-configured) + │ (Port 8000) │ + └───────────────┘ +``` + +**Key Point:** Your browser loads the frontend from port 8502, but that frontend needs to know where to find the API (port 5055). When accessing remotely, you must tell it explicitly: `API_URL=http://your-server-ip:5055` + +## Star History + +[![Star History Chart](https://api.star-history.com/svg?repos=lfnovo/open-notebook&type=date&legend=top-left)](https://www.star-history.com/#lfnovo/open-notebook&type=date&legend=top-left) ### 🛠️ Full Installation For development or customization: diff --git a/docs/getting-started/5-minute-setup.md b/docs/getting-started/5-minute-setup.md new file mode 100644 index 0000000..93d1b4e --- /dev/null +++ b/docs/getting-started/5-minute-setup.md @@ -0,0 +1,137 @@ +# 5-Minute Setup Guide + +**Goal:** Get Open Notebook running as fast as possible. + +## Step 1: Know Your Setup (10 seconds) + +Answer one question: **Where will you ACCESS Open Notebook from?** + +- ✅ **Same computer where Docker runs** → Use `localhost` setup below +- ✅ **Different computer** (accessing a server, Raspberry Pi, NAS, etc.) → Use `remote` setup below + +## Step 2: Install Docker (if needed) + +Already have Docker? Skip to Step 3. + +- **Mac/Windows:** Download [Docker Desktop](https://www.docker.com/products/docker-desktop/) +- **Linux:** `sudo apt install docker.io docker-compose-plugin` + +## Step 3: Get an API Key + +You need at least one AI provider. OpenAI is recommended for beginners: + +1. Go to https://platform.openai.com/api-keys +2. Create account → "Create new secret key" +3. Add $5 in credits +4. Copy the key (starts with `sk-`) + +## Step 4: Run Open Notebook + +### 🏠 For Localhost (Same Computer): + +```bash +mkdir open-notebook && cd open-notebook + +cat > docker-compose.yml << 'EOF' +services: + open_notebook: + image: lfnovo/open_notebook:v1-latest-single + ports: + - "8502:8502" # Web UI + - "5055:5055" # API + environment: + - OPENAI_API_KEY=REPLACE_WITH_YOUR_KEY + volumes: + - ./notebook_data:/app/data + - ./surreal_data:/mydata + restart: always +EOF + +# Edit the file and replace REPLACE_WITH_YOUR_KEY with your actual key +nano docker-compose.yml # or use your preferred editor + +docker compose up -d +``` + +**Access:** http://localhost:8502 + +### 🌐 For Remote Server: + +```bash +mkdir open-notebook && cd open-notebook + +cat > docker-compose.yml << 'EOF' +services: + open_notebook: + image: lfnovo/open_notebook:v1-latest-single + ports: + - "8502:8502" # Web UI + - "5055:5055" # API + environment: + - OPENAI_API_KEY=REPLACE_WITH_YOUR_KEY + - API_URL=http://REPLACE_WITH_SERVER_IP:5055 + volumes: + - ./notebook_data:/app/data + - ./surreal_data:/mydata + restart: always +EOF + +# Edit the file and replace both placeholders +nano docker-compose.yml # or use your preferred editor + +docker compose up -d +``` + +**Find your server IP:** +```bash +# On the server where Docker is running: +hostname -I # Linux +ipconfig # Windows +ifconfig | grep inet # Mac +``` + +**Replace in the file:** +- `REPLACE_WITH_YOUR_KEY` → Your actual OpenAI key +- `REPLACE_WITH_SERVER_IP` → Your server's IP (e.g., `192.168.1.100`) + +**Access:** http://YOUR_SERVER_IP:8502 + +## Step 5: Verify Setup + +1. **Open the URL** in your browser +2. If you see "Unable to connect to server": + - **Remote setup?** Make sure you set `API_URL` with your actual server IP + - **Both ports exposed?** Run `docker ps` and verify you see both 8502 and 5055 + - **Using localhost for remote?** That won't work! Use the actual IP address + +3. If you see the Open Notebook interface: + - Click **Settings** → **Models** + - Configure your default models + - Start creating notebooks! + +**Working?** → Proceed to [Your First Notebook](first-notebook.md) + +**Not working?** → [Quick Troubleshooting Guide](../troubleshooting/quick-fixes.md) + +## Common Mistakes to Avoid + +| ❌ Wrong | ✅ Correct | +|----------|-----------| +| Only exposing port 8502 | Expose BOTH ports: 8502 and 5055 | +| Using `localhost` in API_URL for remote access | Use the actual server IP: `192.168.1.100` | +| Adding `/api` to API_URL | Just use `http://server-ip:5055` | +| Forgetting to restart after config changes | Always run `docker compose down && docker compose up -d` | + +## Next Steps + +Once Open Notebook is running: + +1. **Configure Models** - Settings → Models +2. **Create Your First Notebook** - [Follow this guide](first-notebook.md) +3. **Add Sources** - PDFs, web links, documents +4. **Start Chatting** - Ask questions about your content +5. **Generate Podcasts** - Turn your research into audio + +--- + +**Need help?** Join our [Discord community](https://discord.gg/37XJPXfz2w) for fast support! diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 5cd9a48..ea5a8db 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -1,63 +1,92 @@ # Getting Started with Open Notebook -Welcome to Open Notebook! This section will guide you from discovery to your first successful experience with the platform. +Welcome to Open Notebook! Choose your path below based on what you need. -## Quick Navigation +--- -### 📚 **[Introduction](introduction.md)** -Learn what Open Notebook is, why it matters, and who it's for. -- What is Open Notebook? +## 🚀 **Just Want It Running? (Recommended)** + +**[5-Minute Setup Guide](5-minute-setup.md)** ← **Start here!** + +The fastest path from zero to running Open Notebook. Clear steps, no fluff. + +**Perfect for:** First-time users, quick testing, simple deployments + +--- + +## 📚 **Want to Learn More First?** + +### **[Introduction](introduction.md)** +What is Open Notebook and why should you care? - Key features and benefits - Comparison with Google Notebook LM -- Use cases and target audience +- Use cases and who it's for - System requirements -### ⚡ **[Quick Start](quick-start.md)** -Get up and running in 5 minutes with Docker. -- Prerequisites -- Single command setup -- Basic verification -- Simple example workflow -- Next steps +### **[Quick Start Tutorial](quick-start.md)** +Detailed walkthrough with examples and verification steps. +- Docker setup with explanations +- Localhost vs remote configuration +- Model configuration +- First notebook creation +- Common issues and fixes -### 🔧 **[Installation](installation.md)** -Comprehensive installation guide for all deployment methods. -- System dependencies -- Environment setup -- Service architecture -- Configuration options -- Verification steps +### **[Complete Installation Guide](installation.md)** +Comprehensive guide for all deployment scenarios. +- Multiple installation methods +- All AI provider configurations +- Service architecture deep dive +- Production deployment options +- Advanced troubleshooting -### 🎯 **[Your First Notebook](first-notebook.md)** -Step-by-step guide to creating your first notebook and experiencing core features. -- Understanding the interface -- Creating your first notebook -- Adding sources -- Generating AI notes -- Basic chat interaction +### **[Your First Notebook](first-notebook.md)** +Step-by-step tutorial once Open Notebook is running. +- Interface overview +- Adding different types of sources +- Generating AI-powered notes +- Chat interactions +- Best practices --- -## Recommended Learning Path +## 🆘 **Having Issues?** -1. **Start Here**: Read the [Introduction](introduction.md) to understand what Open Notebook offers -2. **Quick Trial**: Follow the [Quick Start](quick-start.md) for immediate hands-on experience -3. **Full Setup**: Use the [Installation](installation.md) guide for comprehensive deployment -4. **First Success**: Complete the [Your First Notebook](first-notebook.md) tutorial +**Most common problem:** "Unable to connect to server" -## Next Steps +→ **[5-Minute Troubleshooting](../troubleshooting/quick-fixes.md)** - Fast fixes for setup issues -After completing this section, explore: -- **[User Guide](../user-guide/index.md)** - Deep dive into all features -- **[Features](../features/index.md)** - Advanced capabilities like podcasts and transformations -- **[Deployment](../deployment/index.md)** - Production deployment options +→ **[Common Issues Guide](../troubleshooting/common-issues.md)** - Complete troubleshooting reference -## Need Help? - -- 💬 **[Discord Community](https://discord.gg/37XJPXfz2w)** - Get help and share ideas -- 🐛 **[GitHub Issues](https://github.com/lfnovo/open-notebook/issues)** - Report bugs and request features -- 📖 **[Troubleshooting](../troubleshooting/index.md)** - Common issues and solutions +→ **[Discord Community](https://discord.gg/37XJPXfz2w)** - Get help from the community --- -*This getting started guide is designed to take you from zero to productive with Open Notebook. Each section builds on the previous one, but you can also jump to specific sections based on your needs.* \ No newline at end of file +## 📍 Recommended Path + +**New to Open Notebook?** Follow this sequence: + +1. **[5-Minute Setup](5-minute-setup.md)** - Get it running first (5 min) +2. **[Your First Notebook](first-notebook.md)** - Learn by doing (10 min) +3. **[Introduction](introduction.md)** - Understand the full potential (5 min) + +**Already know what you want?** Jump directly to: +- **[Installation Guide](installation.md)** - For production deployments +- **[User Guide](../user-guide/index.md)** - Deep dive into features +- **[Features](../features/index.md)** - Advanced capabilities (podcasts, transformations) + +--- + +## 🎯 Quick Links by Use Case + +| I want to... | Start here | +|-------------|------------| +| **Try Open Notebook now** | [5-Minute Setup](5-minute-setup.md) | +| **Deploy on a remote server** | [5-Minute Setup](5-minute-setup.md) → Remote section | +| **Understand before installing** | [Introduction](introduction.md) | +| **Deploy for production use** | [Installation Guide](installation.md) | +| **Fix installation problems** | [Quick Fixes](../troubleshooting/quick-fixes.md) | +| **Learn all features** | [User Guide](../user-guide/index.md) | + +--- + +*Open Notebook is designed to be simple to start, yet powerful when you need it. Start with the 5-minute setup and explore from there!* \ No newline at end of file diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md index cb5aca0..f0cfbce 100644 --- a/docs/getting-started/quick-start.md +++ b/docs/getting-started/quick-start.md @@ -17,9 +17,17 @@ Before starting, ensure you have: ## Single Command Setup -### Step 1: Create Your Setup Files +### Step 1: Choose Your Setup Method -Create a new folder called `open-notebook` and add these two files: +Are you installing on: +- **🏠 The same computer** you'll use to access Open Notebook? → Use **Local Setup** +- **🌐 A remote server** (Raspberry Pi, NAS, cloud server, Proxmox)? → Use **Remote Setup** + +### Step 2: Create Your Configuration + +Create a new folder called `open-notebook` and add these files: + +#### For Local Machine (Same Computer): **docker-compose.yml**: ```yaml @@ -27,7 +35,8 @@ services: open_notebook: image: lfnovo/open_notebook:v1-latest-single ports: - - "8502:8502" + - "8502:8502" # Web UI + - "5055:5055" # API (required!) env_file: - ./docker.env pull_policy: always @@ -50,15 +59,61 @@ SURREAL_NAMESPACE="open_notebook" SURREAL_DATABASE="production" ``` -### Step 2: Start Open Notebook +#### For Remote Server: + +**docker-compose.yml**: +```yaml +services: + open_notebook: + image: lfnovo/open_notebook:v1-latest-single + ports: + - "8502:8502" # Web UI + - "5055:5055" # API (required!) + env_file: + - ./docker.env + pull_policy: always + volumes: + - ./notebook_data:/app/data + - ./surreal_single_data:/mydata + restart: always +``` + +**docker.env**: +```env +# Replace YOUR_OPENAI_API_KEY_HERE with your actual API key +OPENAI_API_KEY=YOUR_OPENAI_API_KEY_HERE + +# CRITICAL: Replace YOUR_SERVER_IP with your server's actual IP address +# Example: API_URL=http://192.168.1.100:5055 +API_URL=http://YOUR_SERVER_IP:5055 + +# Database settings (don't change these) +SURREAL_URL="ws://localhost:8000/rpc" +SURREAL_USER="root" +SURREAL_PASSWORD="root" +SURREAL_NAMESPACE="open_notebook" +SURREAL_DATABASE="production" +``` + +> **⚠️ Finding Your Server IP:** +> On the server running Docker, use: +> - **Linux**: `hostname -I` or `ip addr show` +> - **Windows**: `ipconfig` (look for IPv4 Address) +> - **Mac**: `ifconfig | grep inet` + +### Step 3: Start Open Notebook Open terminal/command prompt in your `open-notebook` folder and run: ```bash -docker-compose up -d +docker compose up -d ``` -**That's it!** Open Notebook is now running at: **http://localhost:8502** +**That's it!** Open Notebook is now running. + +**Access at:** +- **Local setup**: http://localhost:8502 +- **Remote setup**: http://YOUR_SERVER_IP:8502 (replace with your actual IP) ## Basic Verification @@ -123,27 +178,53 @@ Now that you have Open Notebook running: ## Common Issues -### Port Already in Use -```bash -docker-compose down -docker-compose up -d -``` +### ❌ "Unable to connect to server" Error + +**This is the #1 issue!** The frontend can't reach the API. + +**Quick Fix Checklist:** + +1. **Are you accessing from a different computer than where Docker runs?** + - ✅ Yes → You MUST set `API_URL` in your `docker.env` (see Remote Setup above) + - ❌ No → Skip to step 2 + +2. **Is port 5055 exposed?** + ```bash + docker ps + # Should show both: 0.0.0.0:8502->8502 AND 0.0.0.0:5055->5055 + ``` + - ❌ Missing 5055? Add it to your `docker-compose.yml` ports section + +3. **Restart after changes:** + ```bash + docker compose down + docker compose up -d + ``` + +**Still not working?** See the [complete troubleshooting guide](../troubleshooting/quick-fixes.md). ### API Key Errors - Double-check your API key in `docker.env` - Ensure you have credits in your OpenAI account - Verify no extra spaces around the key +- Key should start with `sk-` + +### Port Already in Use +```bash +docker compose down +docker compose up -d +``` ### Container Won't Start ```bash -docker-compose down -v -docker-compose up -d +docker compose down -v +docker compose up -d ``` ### Can't Access Interface - Ensure Docker Desktop is running -- Check firewall isn't blocking port 8502 -- Try: `docker-compose restart` +- Check firewall isn't blocking ports 8502 and 5055 +- Try: `docker compose restart` ## Stopping Open Notebook diff --git a/docs/troubleshooting/common-issues.md b/docs/troubleshooting/common-issues.md index 82deaa2..c6b4ae9 100644 --- a/docs/troubleshooting/common-issues.md +++ b/docs/troubleshooting/common-issues.md @@ -2,6 +2,135 @@ This document covers the most frequently encountered issues when installing, configuring, and using Open Notebook, along with their solutions. +> **🆘 Quick Fixes for Setup Issues** +> +> Most problems are caused by incorrect API_URL configuration. Choose your scenario below for instant fixes. + +## Setup-Related Issues (START HERE!) + +### ❌ "Unable to connect to server" or "Connection Error" + +**This is the #1 issue for new users.** The frontend can't reach the API. + +#### Diagnostic Checklist: + +1. **Are both ports exposed?** + ```bash + docker ps + # Should show: 0.0.0.0:8502->8502 AND 0.0.0.0:5055->5055 + ``` + ✅ **Fix:** Add `-p 5055:5055` to your docker run command, or add it to docker-compose.yml: + ```yaml + ports: + - "8502:8502" + - "5055:5055" # Add this! + ``` + +2. **Are you accessing from a different machine than where Docker is running?** + + **Determine your server's IP:** + ```bash + # On the Docker host machine: + hostname -I # Linux + ipconfig # Windows + ifconfig | grep inet # Mac + ``` + + ✅ **Fix:** Set environment variable (replace with your actual server IP): + + **Docker Compose:** + ```yaml + environment: + - API_URL=http://192.168.1.100:5055 + ``` + + **Docker Run:** + ```bash + -e API_URL=http://192.168.1.100:5055 + ``` + +3. **Using localhost in API_URL but accessing remotely?** + + ❌ **Wrong:** + ``` + Access from browser: http://192.168.1.100:8502 + API_URL setting: http://localhost:5055 # This won't work! + ``` + + ✅ **Correct:** + ``` + Access from browser: http://192.168.1.100:8502 + API_URL setting: http://192.168.1.100:5055 + ``` + +#### Common Scenarios: + +| Your Setup | Access URL | API_URL Value | +|------------|-----------|---------------| +| Docker on your laptop, accessed locally | `http://localhost:8502` | Not needed (or `http://localhost:5055`) | +| Docker on Proxmox VM at 192.168.1.50 | `http://192.168.1.50:8502` | `http://192.168.1.50:5055` | +| Docker on Raspberry Pi at 10.0.0.10 | `http://10.0.0.10:8502` | `http://10.0.0.10:5055` | +| Docker on NAS at nas.local | `http://nas.local:8502` | `http://nas.local:5055` | +| Behind reverse proxy at notebook.mydomain.com | `https://notebook.mydomain.com` | `https://notebook.mydomain.com/api` | + +#### After changing API_URL: + +**Always restart the container:** +```bash +# Docker Compose +docker compose down +docker compose up -d + +# Docker Run +docker stop open-notebook +docker rm open-notebook +# Then run your docker run command again +``` + +--- + +### ❌ Frontend trying to connect on port 8502 instead of 5055 + +**Symptom:** Frontend tries to access `http://10.10.10.107:8502/api/config` instead of using port 5055. + +**Cause:** API_URL is not set correctly or you're using an old version. + +✅ **Fix:** +1. Ensure you're using version 1.0.6+ which supports runtime API_URL +2. Set API_URL environment variable (not NEXT_PUBLIC_API_URL) +3. Restart container after setting the variable + ```bash + docker compose down && docker compose up -d + ``` + +--- + +### ❌ "API config endpoint returned status 404" + +**Cause:** You added `/api` to the end of API_URL. + +❌ **Wrong:** `API_URL=http://192.168.1.100:5055/api` + +✅ **Correct:** `API_URL=http://192.168.1.100:5055` + +The `/api` path is added automatically by the application. + +--- + +### ❌ "Missing authorization header" + +**Cause:** You have password authentication enabled but it's not configured correctly. + +✅ **Fix:** Set the password in your environment: +```yaml +environment: + - OPEN_NOTEBOOK_PASSWORD=your_secure_password +``` + +Or provide it when logging into the web interface. + +--- + ## Installation Problems ### Port Already in Use diff --git a/docs/troubleshooting/quick-fixes.md b/docs/troubleshooting/quick-fixes.md new file mode 100644 index 0000000..a829292 --- /dev/null +++ b/docs/troubleshooting/quick-fixes.md @@ -0,0 +1,306 @@ +# 5-Minute Troubleshooting + +**Problem:** Something isn't working? Let's fix it fast. + +## Start Here: What's Your Issue? + +Click your problem: + +### 1. ["Unable to connect to server" or blank page](#fix-connection-error) +### 2. [Container won't start or crashes](#fix-container-crash) +### 3. [Works on server but not from my computer](#fix-remote-access) +### 4. [API or authentication errors](#fix-api-errors) +### 5. [Slow or timeout errors](#fix-performance) + +--- + + +## Fix: "Unable to connect to server" + +This means your frontend can't reach the API. **99% of the time, this is an API_URL problem.** + +### Step-by-Step Fix: + +1. **Check if API is running:** + ```bash + curl http://localhost:5055/health + # Should return: {"status": "healthy"} or similar + ``` + + - ❌ **Connection refused?** → Port 5055 is not exposed. [Jump to port fix](#fix-missing-port) + - ✅ **Got response?** → API is running, continue below. + +2. **Are you accessing from a different machine?** + + - Your browser on **Computer A** + - Docker running on **Computer B** (server, Raspberry Pi, NAS, etc.) + + → **You MUST set API_URL** + + Find your server's IP: + ```bash + # On the server running Docker: + hostname -I # Linux + ipconfig # Windows + ifconfig # Mac + ``` + + Set API_URL (replace 192.168.1.100 with YOUR server IP): + + **Docker Compose** - Add to your `docker-compose.yml`: + ```yaml + environment: + - OPENAI_API_KEY=your_key + - API_URL=http://192.168.1.100:5055 + ``` + + **Docker Run** - Add this flag: + ```bash + -e API_URL=http://192.168.1.100:5055 + ``` + + Then restart: + ```bash + docker compose down && docker compose up -d + # or for docker run, stop and restart the container + ``` + +3. **Still not working?** + + Check what URL your browser is trying to access: + - Open browser DevTools (F12) + - Go to Network tab + - Refresh the page + - Look for failed requests to `/api/config` + + The URL should match: `http://YOUR_SERVER_IP:5055/api/config` + + If it shows `localhost:5055` or wrong IP, your API_URL is not set correctly. + + +### Fix: Port 5055 Not Exposed + +**Check currently exposed ports:** +```bash +docker ps +# Look for: 0.0.0.0:5055->5055 +``` + +**Not there?** Add it: + +**Docker Compose** - Update your `docker-compose.yml`: +```yaml +services: + open_notebook: + ports: + - "8502:8502" + - "5055:5055" # Add this line! +``` + +**Docker Run** - Add `-p 5055:5055`: +```bash +docker run -d \ + -p 8502:8502 \ + -p 5055:5055 \ # Add this! + # ... rest of your command +``` + +Then restart the container. + +--- + + +## Fix: Container Won't Start + +**Check the logs:** +```bash +docker logs open-notebook +# or +docker compose logs +``` + +### Common causes: + +| Error Message | Fix | +|---------------|-----| +| "Port already in use" | Change port: `-p 8503:8502` or stop conflicting service | +| "Permission denied" | Add user to docker group: `sudo usermod -aG docker $USER` (then log out/in) | +| "Invalid API key" | Check OPENAI_API_KEY in environment variables | +| "Out of memory" | Increase Docker memory limit to 2GB+ in Docker Desktop settings | +| "No such file or directory" | Check volume paths exist and are accessible | + +**Quick reset:** +```bash +docker compose down -v +docker compose up -d +``` + +--- + + +## Fix: Works on Server But Not From My Computer + +**Symptom:** Open Notebook works when accessed on the server itself (`localhost:8502`) but not from another computer. + +**This is 100% an API_URL problem.** + +✅ **The Fix:** + +Your API_URL must match the URL you use to access Open Notebook. + +| You access via | Set API_URL to | +|----------------|----------------| +| `http://192.168.1.50:8502` | `http://192.168.1.50:5055` | +| `http://myserver:8502` | `http://myserver:5055` | +| `http://10.0.0.5:8502` | `http://10.0.0.5:5055` | + +**Apply the fix:** + +1. Edit your `docker-compose.yml`: + ```yaml + environment: + - OPENAI_API_KEY=your_key + - API_URL=http://YOUR_SERVER_IP_OR_HOSTNAME:5055 + ``` + +2. Or edit your `docker.env` file: + ```env + API_URL=http://YOUR_SERVER_IP_OR_HOSTNAME:5055 + ``` + +3. Restart: + ```bash + docker compose down && docker compose up -d + ``` + +**Common mistakes:** +- ❌ Using `localhost` in API_URL when accessing remotely +- ❌ Using your client computer's IP instead of the server's IP +- ❌ Adding `/api` to the end (it's automatic) + +--- + + +## Fix: API or Authentication Errors + +### "Missing authorization header" + +You have password auth enabled. Make sure it's set correctly: + +```yaml +environment: + - OPEN_NOTEBOOK_PASSWORD=your_password +``` + +Or provide the password when logging into the web interface. + +### "API config endpoint returned status 404" + +You added `/api` to API_URL. Remove it: + +❌ **Wrong:** `API_URL=http://192.168.1.100:5055/api` + +✅ **Correct:** `API_URL=http://192.168.1.100:5055` + +The `/api` path is added automatically by the application. + +### "Invalid API key" or "Incorrect API key" + +1. Check key format (OpenAI keys start with `sk-`) +2. Verify you have credits in your provider account +3. Check for spaces around the key in your .env file: + ```env + # Wrong - has spaces + OPENAI_API_KEY = sk-your-key + + # Correct + OPENAI_API_KEY=sk-your-key + ``` +4. Test your key directly: + ```bash + curl https://api.openai.com/v1/models \ + -H "Authorization: Bearer YOUR_KEY" + ``` + +--- + + +## Fix: Slow or Timeout Errors + +### Increase timeouts for local models: + +If you're using Ollama or LM Studio: + +```yaml +environment: + - API_CLIENT_TIMEOUT=600 # 10 minutes + - ESPERANTO_LLM_TIMEOUT=180 # 3 minutes +``` + +**Recommended timeouts by setup:** +- Cloud APIs (OpenAI, Anthropic): Default (300s) +- Local Ollama with GPU: 600s +- Local Ollama with CPU: 1200s +- Remote LM Studio: 900s + +### Use faster models: + +- **Cloud APIs:** OpenAI, Anthropic, Groq (fastest) +- **Local models:** Try smaller models first + - Fast: `gemma2:2b`, `phi3:mini` + - Medium: `llama3:8b`, `mistral:7b` + - Slow: `llama3:70b`, `mixtral:8x7b` + +### Preload local models: + +```bash +# This prevents first-run delays +ollama run llama3 +# Press Ctrl+D to exit after model loads +``` + +--- + +## Still Stuck? + +### Collect diagnostics: + +```bash +# Container status +docker ps + +# Container logs (last 100 lines) +docker logs --tail 100 open-notebook > logs.txt + +# Or for docker compose +docker compose logs --tail 100 > logs.txt + +# Check resource usage +docker stats --no-stream +``` + +### Get help: + +1. **[Discord](https://discord.gg/37XJPXfz2w)** - Fastest response from community +2. **[GitHub Issues](https://github.com/lfnovo/open-notebook/issues)** - Bug reports and features +3. **[Full Troubleshooting Guide](common-issues.md)** - More detailed solutions + +**Before asking:** +- Include your `docker-compose.yml` (remove API keys!) +- Include relevant logs +- Describe your setup (local vs remote, OS, Docker version) +- What you've already tried + +--- + +## Quick Reference: API_URL Settings + +| Scenario | API_URL Value | Example | +|----------|---------------|---------| +| **Local access only** | Not needed | Leave unset | +| **Remote on same network** | `http://SERVER_IP:5055` | `http://192.168.1.100:5055` | +| **Remote with hostname** | `http://HOSTNAME:5055` | `http://myserver.local:5055` | +| **Behind reverse proxy (no SSL)** | `http://DOMAIN:5055` | `http://notebook.local:5055` | +| **Behind reverse proxy (SSL)** | `https://DOMAIN/api` | `https://notebook.example.com/api` | + +**Remember:** The API_URL is from your **browser's perspective**, not the server's!