admin-valentin/open-notebook
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: setup

Browse source
This commit is contained in:
LUIS NOVO 2025-10-20 15:25:28 -03:00
parent 9a6d507217
commit 12bd2655a4
6 changed files with 856 additions and 75 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

133
README.md
View file

@ -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:
<table>
<tr>
<td width="50%">
#### 🏠 **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
</td>
<td width="50%">
#### 🌐 **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
</td>
</tr>
</table>
> **⚠️ 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:

137
docs/getting-started/5-minute-setup.md Normal file
View file

@ -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!

115
docs/getting-started/index.md
View file

@ -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.*
## 📍 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!*

111
docs/getting-started/quick-start.md
View file

@ -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

129
docs/troubleshooting/common-issues.md
View file

@ -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

306
docs/troubleshooting/quick-fixes.md Normal file
View file

@ -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)
---
<a name="fix-connection-error"></a>
## 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.
<a name="fix-missing-port"></a>
### 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.
---
<a name="fix-container-crash"></a>
## 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
```
---
<a name="fix-remote-access"></a>
## 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)
---
<a name="fix-api-errors"></a>
## 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"
```
---
<a name="fix-performance"></a>
## 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!