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

Configuration - Essential Settings

Configuration is how you customize Open Notebook for your specific setup. This section covers what you need to know.

---

What Needs Configuration?

Three things:

1. AI Provider — Which LLM/embedding service you're using (OpenAI, Anthropic, Ollama, etc.)
2. Database — How to connect to SurrealDB (usually pre-configured)
3. Server — API URL, ports, timeouts (usually auto-detected)

---

Quick Decision: Which Provider?

Option 1: Cloud Provider (Fastest)

• OpenRouter (recommended) (access to all models with one key)
• OpenAI (GPT)
• Anthropic (Claude)
• Google Gemini (multi-modal, long context)
• Groq (ultra-fast inference)

Setup: Get API key → Add credential in Settings UI → Done

→ Go to AI Providers Guide

Option 2: Local (Free & Private)

• Ollama (open-source models, on your machine)

→ Go to Ollama Setup

Option 3: OpenAI-Compatible

• LM Studio (local)
• Custom endpoints

→ Go to OpenAI-Compatible Guide

---

Configuration File

Use the right file depending on your setup.

.env (Local Development)

You will only use .env if you are running Open Notebook locally.

Located in: project root
Use for: Development on your machine
Format: KEY=value, one per line

docker.env (Docker Deployment)

You will use this file to hold your environment variables if you are using docker-compose and prefer not to put the variables directly in the compose file.

Located in: project root (or ./docker)
Use for: Docker deployments
Format: Same as .env
Loaded by: docker-compose.yml

---

Most Important Settings

All of the settings provided below are to be placed inside your environment file (.env or docker.env depending on your setup).

Surreal Database

This is the database used by the app.

SURREAL_URL=ws://surrealdb:8000/rpc
SURREAL_USER=root
SURREAL_PASSWORD=root  # Change in production!
SURREAL_NAMESPACE=open_notebook
SURREAL_DATABASE=open_notebook

The only thing that is critical to not miss is the hostname in the SURREAL_URL. Check what URL to use based on your deployment, here.

AI Provider (Credentials)

We need access to LLMs in order for the app to work. AI provider credentials are configured via the Settings UI:

1. Set OPEN_NOTEBOOK_ENCRYPTION_KEY in your environment (required for storing credentials)
2. Start services
3. Go to Settings → API Keys → Add Credential
4. Select your provider, paste your API key
5. Test Connection → Discover Models → Register Models

# Required in your .env or docker-compose.yml:
OPEN_NOTEBOOK_ENCRYPTION_KEY=my-secret-key

Ollama users: Add an Ollama credential in Settings → API Keys with the correct base URL. See Ollama Setup for network configuration help.

LM Studio / OpenAI-Compatible: Add an OpenAI-Compatible credential in Settings → API Keys. See OpenAI-Compatible Guide.

API URL (If Behind Reverse Proxy)

You only need to worry about this if you are deploying on a proxy or if you are changing port information. Otherwise, skip this.

API_URL=https://your-domain.com
# Usually auto-detected. Only set if needed.

Auto-detection works for most setups.

---

Configuration by Scenario

Scenario 1: Docker on Localhost (Default)

# In docker.env:
OPEN_NOTEBOOK_ENCRYPTION_KEY=my-secret-key
# Everything else uses defaults
# Then configure AI provider in Settings → API Keys

Scenario 2: Docker on Remote Server

# In docker.env:
OPEN_NOTEBOOK_ENCRYPTION_KEY=my-secret-key
API_URL=http://your-server-ip:5055

Scenario 3: Behind Reverse Proxy (Nginx/Cloudflare)

# In docker.env:
OPEN_NOTEBOOK_ENCRYPTION_KEY=my-secret-key
API_URL=https://your-domain.com
# The reverse proxy handles HTTPS

Scenario 4: Using Ollama Locally

# In .env:
OPEN_NOTEBOOK_ENCRYPTION_KEY=my-secret-key
# Then add Ollama credential in Settings → API Keys

Scenario 5: Using Azure OpenAI

# In docker.env:
OPEN_NOTEBOOK_ENCRYPTION_KEY=my-secret-key
# Then add Azure OpenAI credential in Settings → API Keys

---

Configuration Sections

AI Providers

• OpenAI configuration
• Anthropic configuration
• Google Gemini configuration
• Groq configuration
• Ollama configuration
• Azure OpenAI configuration
• OpenAI-compatible configuration

Database

• SurrealDB setup
• Connection strings
• Database vs. namespace
• Running your own SurrealDB

Advanced

• Ports and networking
• Timeouts and concurrency
• SSL/security
• Retry configuration
• Worker concurrency
• Language models & embeddings
• Speech-to-text & text-to-speech
• Debugging and logging

Reverse Proxy

• Nginx, Caddy, Traefik configs
• Custom domain setup
• SSL/HTTPS configuration
• Coolify and other platforms

Security

• Password protection
• API authentication
• Production hardening
• Firewall configuration

Local TTS

• Speaches setup for local text-to-speech
• GPU acceleration
• Voice options
• Docker networking

Local STT

• Speaches setup for local speech-to-text
• Whisper model options
• GPU acceleration
• Docker networking

Ollama

• Setting up and pointing to an Ollama server
• Downloading models
• Using embedding

OpenAI-Compatible Providers

• LM Studio, vLLM, Text Generation WebUI
• Connection configuration
• Docker networking
• Troubleshooting

Complete Reference

• All environment variables
• Grouped by category
• What each one does
• Default values

---

How to Add Configuration

Method 1: Settings UI (For AI Provider Credentials)

The recommended way to configure AI providers:

1. Open Open Notebook in your browser
2. Go to Settings → API Keys
3. Click "Add Credential"
4. Select provider, enter API key
5. Click Save, then Test Connection
6. Click Discover Models → Register Models

No file editing, no restarts. Credentials stored securely (encrypted) in database.

→ Full Guide: API Configuration

Method 2: Edit .env File (Infrastructure Settings)

For database, network, and encryption key settings:

1. Open .env in your editor
2. Set OPEN_NOTEBOOK_ENCRYPTION_KEY and database vars
3. Save
4. Restart services

Method 3: Set Docker Environment (Deployment)

# In docker-compose.yml:
services:
  api:
    environment:
      - OPEN_NOTEBOOK_ENCRYPTION_KEY=my-secret-key
      - API_URL=https://your-domain.com

---

Verification

After configuration, verify it works:

1. Open your notebook
2. Go to Settings → Models
3. You should see your configured provider
4. Try a simple Chat question
5. If it responds, configuration is correct!

---

Common Mistakes

Mistake	Problem	Fix
No credential configured	Models not available	Add credential in Settings → API Keys
Missing encryption key	Can't save credentials	Set OPEN_NOTEBOOK_ENCRYPTION_KEY
Wrong database URL	Can't start API	Check SURREAL_URL format
Expose port 5055	"Can't connect to server"	Expose 5055 in docker-compose
Typo in env var	Settings ignored	Check spelling (case-sensitive!)
Don't restart	Old config still used	Restart services after env changes

---

What Comes After Configuration

Once configured:

1. Quick Start — Run your first notebook
2. Installation — Multi-route deployment guides
3. User Guide — How to use each feature

---

Getting Help

• Configuration error? → Check Troubleshooting
• Provider-specific issue? → Check AI Providers
• Need complete reference? → See Environment Reference

---

Summary

Minimal configuration to run:

1. Set OPEN_NOTEBOOK_ENCRYPTION_KEY in your environment
2. Start services
3. Add AI provider credential in Settings → API Keys
4. Done!

Everything else is optional optimization.