open-notebook/docs/5-CONFIGURATION/server.md

Server - API & Network Configuration

Configuration for how Open Notebook's API and frontend communicate.

---

Most Important: API_URL

What it does: Tells the frontend where to find the API.

Default behavior: Auto-detected (usually works!)

When to set it: Only if auto-detection doesn't work (reverse proxy, custom domain, etc.)

---

Auto-Detection (Default)

Open Notebook automatically detects the API URL from your request:

You visit: http://localhost:8502
It detects: http://localhost:5055 (same host, port 5055)

You visit: http://myserver.com:8502
It detects: http://myserver.com:5055 (same host, port 5055)

You visit: https://myserver.com
It detects: https://myserver.com:5055 (same host, port 5055)

This works because:

• Frontend and API are usually on same host
• API is always on port 5055
• System uses the hostname you're accessing from

---

When to Set API_URL

Set API_URL only in these cases:

Case 1: Behind Reverse Proxy

# You access via: https://mynotebook.example.com
# But API is actually: https://api.example.com:5055

API_URL=https://api.example.com:5055

Case 2: Custom Domain

# You access via: https://notebook.mycompany.com
# API should be at: https://notebook.mycompany.com/api

API_URL=https://notebook.mycompany.com
# System will auto-add /api to the end

Case 3: Different Port

# You access via: http://localhost:3055 (custom port)
# API is on: http://localhost:3055

API_URL=http://localhost:3055

Case 4: Explicitly Disable Auto-Detection

# Force a specific URL (override auto-detection)
API_URL=http://192.168.1.100:5055

---

How to Configure

Method 1: .env File (Development)

# .env
API_URL=http://localhost:5055

Restart services:

make api  # or your restart command

Method 2: docker.env (Docker)

# docker.env
API_URL=https://mynotebook.example.com

Restart:

docker compose restart frontend

Method 3: Environment Variable

export API_URL=https://mynotebook.example.com
docker compose up

Method 4: docker-compose Override

services:
  frontend:
    environment:
      - API_URL=https://mynotebook.example.com

---

Port Configuration

Default Ports

Frontend: 3000 (dev) or 8502 (docker)
API: 5055
SurrealDB: 8000

Changing Frontend Port

Edit docker-compose.yml:

services:
  frontend:
    ports:
      - "8001:3000"  # Change from 8502 to 8001

Access at: http://localhost:8001

API auto-detects to: http://localhost:5055 ✓

Changing API Port

services:
  api:
    ports:
      - "5056:5055"  # Change from 5055 to 5056
    environment:
      - API_URL=http://localhost:5056  # Explicitly set

Access API directly: http://localhost:5056/docs

Changing SurrealDB Port

services:
  surrealdb:
    ports:
      - "8001:8000"  # Change from 8000 to 8001
    environment:
      - SURREAL_URL=ws://surrealdb:8001/rpc  # Update connection

---

Timeouts

How long to wait before giving up on operations.

API_CLIENT_TIMEOUT

Controls how long the frontend waits for API responses.

# Default: 300 seconds (5 minutes)
API_CLIENT_TIMEOUT=300

When to increase:

• Using Ollama on CPU (slow)
• Remote servers with high latency
• Large document processing
• Slow embeddings

Examples:

# Ollama on GPU
API_CLIENT_TIMEOUT=300  # Default is fine

# Ollama on CPU
API_CLIENT_TIMEOUT=600  # 10 minutes

# Very large documents
API_CLIENT_TIMEOUT=900  # 15 minutes

ESPERANTO_LLM_TIMEOUT

Timeout for individual LLM API calls (at the library level).

# Default: 60 seconds
ESPERANTO_LLM_TIMEOUT=60

When to increase:

• Large model inference times
• Self-hosted LLMs on slow hardware
• Rate-limited APIs

Examples:

# OpenAI/Anthropic (fast)
ESPERANTO_LLM_TIMEOUT=60  # Default fine

# Ollama large models on CPU
ESPERANTO_LLM_TIMEOUT=180  # 3 minutes

# Self-hosted remote LLM
ESPERANTO_LLM_TIMEOUT=300  # 5 minutes

Note: Set API_CLIENT_TIMEOUT higher than ESPERANTO_LLM_TIMEOUT for proper error handling.

---

SSL/HTTPS

Basic Setup

If using HTTPS (reverse proxy, custom domain):

API_URL=https://mynotebook.example.com

The system auto-detects protocol from your request (HTTP or HTTPS).

Self-Signed Certificates

If using self-signed certs for local providers (Ollama, LM Studio behind proxy):

Option 1: Disable Verification (Development Only)

# WARNING: Only for development/testing
# Exposes you to man-in-the-middle attacks
ESPERANTO_SSL_VERIFY=false

Option 2: Custom CA Bundle (Recommended)

# Point to your CA certificate
ESPERANTO_SSL_CA_BUNDLE=/path/to/ca-bundle.pem

To create CA bundle:

# Copy your certificate
cp your-cert.pem /path/to/ca-bundle.pem

# Or combine multiple certs
cat cert1.pem cert2.pem > ca-bundle.pem

---

Reverse Proxy Setup

If you're running Open Notebook behind Nginx, Traefik, etc.:

Nginx Example

server {
    server_name mynotebook.example.com;
    listen 443 ssl;

    # Configure SSL...
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    # Frontend
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    # API
    location /api {
        proxy_pass http://localhost:5055/api;
        proxy_http_version 1.1;
    }
}

Configuration:

API_URL=https://mynotebook.example.com

Cloudflare Reverse Proxy Example

# If using Cloudflare or similar
API_URL=https://mynotebook.example.com

# You may need to preserve headers
# (Cloudflare usually handles this automatically)

---

CORS Configuration

Open Notebook automatically configures CORS to allow:

• Same domain access
• Localhost access (for development)
• Your specified API_URL

Usually no configuration needed.

If you get CORS errors:

1. Check API_URL matches your frontend URL
2. Verify no typos in domain names
3. Ensure HTTPS vs HTTP matches throughout

---

Health Check

Test if API is running and accessible:

# From your machine:
curl http://localhost:5055/health

# Expected response:
# {"status":"ok"}

# If behind reverse proxy:
curl https://mynotebook.example.com/health

---

Testing Configuration

Step 1: Start Services

docker compose up -d

Step 2: Test Frontend

# Open in browser
http://localhost:8502  # or your custom port

Step 3: Test API

# Direct API access
curl http://localhost:5055/docs

# Should show Swagger UI

Step 4: Test Connection

1. Open Open Notebook in browser
2. Go to create notebook
3. If works, configuration is correct!

Step 5: Check Logs

# If there's an issue
docker compose logs frontend | grep -i "api\|error"
docker compose logs api | grep -i "error"

---

Troubleshooting

"Cannot connect to API" or "Unable to reach server"

Cause: Frontend can't reach API

Checks:

1. Is API running? docker ps | grep api
2. Is port 5055 exposed? netstat -tlnp | grep 5055
3. Is API_URL correct? Check browser console (F12)
4. Is frontend accessing the right domain?

Fix:

# Explicit API_URL
API_URL=http://localhost:5055
# Restart
docker compose restart

"Mixed content" or HTTPS warning

Cause: Frontend is HTTPS but API is HTTP (or vice versa)

Fix:

# Make both HTTPS
API_URL=https://mynotebook.example.com

# And ensure reverse proxy uses HTTPS

Slow responses

Cause: Timeout too short for your setup

Fix:

# Increase timeout
API_CLIENT_TIMEOUT=600
# Restart
docker compose restart

404 on /api endpoints

Cause: Reverse proxy not forwarding /api correctly

Fix (Nginx example):

location /api {
    proxy_pass http://localhost:5055/api;  # Keep /api in path
}

---

Summary

For most setups:

1. Leave API_URL unset (auto-detection works)
2. Keep default ports (3000/8502 frontend, 5055 API)
3. Only set API_URL if behind reverse proxy

Quick checklist:

• Frontend can access API (test with curl)
• Ports are exposed correctly
• API_URL matches your frontend URL
• HTTPS/HTTP consistent throughout
• Timeouts set for your hardware speed

If everything works, you're good!