How to Install Open Notebook: A Guide for Docker and Source Setup

To get Open Notebook running on your machine, you can choose between a streamlined Docker deployment or a manual installation from the source code.

Docker Installation (Recommended for Most Users)

# Create a project directory
mkdir open-notebook && cd open-notebook

# Download the configuration files
curl -O https://raw.githubusercontent.com/lfnovo/open-notebook/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/lfnovo/open-notebook/main/.env.example

# Rename the environment file and configure your keys
mv .env.example docker.env
# Edit docker.env to add your API keys.

# Start the application stack
docker compose up -d

Source Installation (Recommended for Developers)

# Clone the repository and prepare the environment
git clone https://github.com/lfnovo/open-notebook
cd open-notebook
cp .env.example .env
# Edit the .env file and insert your API keys.

# Install dependencies and launch the services
uv sync
make start-all

Once the setup is complete, navigate to http://localhost:8502 in your browser to begin.

System Requirements

Hardware

• CPU: 2 cores minimum; 4 or more cores recommended for better performance.
• RAM: 4GB minimum; 8GB or more is ideal for production use.
• Storage: At least 10GB of free space.
• Network: A stable internet connection to communicate with AI service endpoints.

Operating System Support

• macOS: 10.15 (Catalina) or newer.
• Linux: Ubuntu 18.04+, Debian 9+, CentOS 7+, Fedora 30+.
• Windows: Windows 10 or newer via WSL2.

Software Prerequisites

• Python: 3.9+ (required for source installation).
• Docker: The latest stable release (required for Docker deployment).
• uv: A fast Python package manager (required for source installation).

Choosing an Installation Method

Service Architecture

Open Notebook consists of four primary components working in tandem:

1. SurrealDB (Port 8000)

• Manages notebooks, sources, notes, and metadata.
• Utilizes SurrealDB, a modern multi-model database.
• Runs as a containerized service with persistent disk storage.

2. FastAPI Backend (Port 5055)

• Serves as the REST API for all core features.
• Includes interactive documentation, authentication, and data validation.
• Key endpoints include /api/notebooks, /api/sources, /api/notes, and /api/chat.

3. Background Task Worker

• Manages resource-intensive asynchronous operations.
• Handles podcast generation, content transformations, and embedding creation.
• Powered by the Surreal Commands task management system.

4. Streamlit UI (Port 8502)

• The primary web interface for user interaction.
• Provides access to notebooks, chat interfaces, search, and note management.
• Built on the Streamlit framework.

Request Lifecycle:

Browser → Streamlit UI → FastAPI Backend → SurrealDB
                    ↓
         Background Worker ← Task Queue

Configuring Environment Variables

Open Notebook stores its configuration in a .env file (or docker.env for Docker users).

General Settings

# Security (Recommended for public-facing deployments)
OPEN_NOTEBOOK_PASSWORD=your_secure_password

# Database Configuration
SURREAL_URL="ws://localhost:8000/rpc"
SURREAL_USER="root"
SURREAL_PASSWORD="root"
SURREAL_NAMESPACE="open_notebook"
SURREAL_DATABASE="production"

AI Provider API Keys

OpenAI

# Supports language models, embeddings, TTS, and STT
OPENAI_API_KEY=sk-your-key-here

Anthropic (Claude)

# For high-quality reasoning and language generation
ANTHROPIC_API_KEY=sk-ant-your-key-here

Google (Gemini)

# Large context windows, embeddings, and TTS
GEMINI_API_KEY=your-gemini-key

Vertex AI (Google Cloud)

# Enterprise-grade model access
VERTEX_PROJECT=your-gcp-project-name
GOOGLE_APPLICATION_CREDENTIALS=./google-credentials.json
VERTEX_LOCATION=us-east5

Additional Providers

# DeepSeek — Cost-effective processing
DEEPSEEK_API_KEY=your-deepseek-key

# Mistral — European-based models
MISTRAL_API_KEY=your-mistral-key

# Groq — High-speed inference
GROQ_API_KEY=your-groq-key

# xAI (Grok) — Advanced reasoning
XAI_API_KEY=your-xai-key

# ElevenLabs — Premium voice synthesis
ELEVENLABS_API_KEY=your-elevenlabs-key

# Ollama — Support for local models
OLLAMA_API_BASE="http://localhost:11434"

# OpenRouter — Aggregated multi-model access
OPENROUTER_BASE_URL="https://openrouter.ai/api/v1"
OPENROUTER_API_KEY=your-openrouter-key

# Azure OpenAI
AZURE_OPENAI_API_KEY=your-azure-key
AZURE_OPENAI_ENDPOINT=https://your-endpoint.openai.azure.com/
AZURE_OPENAI_API_VERSION="2024-12-01-preview"
AZURE_OPENAI_DEPLOYMENT_NAME=your-deployment-name

# OpenAI-Compatible Services (e.g., LM Studio)
OPENAI_COMPATIBLE_BASE_URL=http://localhost:1234/v1
OPENAI_COMPATIBLE_API_KEY=your-key # Optional

Optional Integration Services

# Firecrawl — Optimized web scraping
FIRECRAWL_API_KEY=your-firecrawl-key

# Jina — Advanced embedding models
JINA_API_KEY=your-jina-key

# Voyage AI — High-performance embeddings
VOYAGE_API_KEY=your-voyage-key

# LangSmith — Monitoring and debugging
LANGCHAIN_TRACING_V2=true
LANGCHAIN_ENDPOINT="https://api.smith.langchain.com"
LANGCHAIN_API_KEY=your-langsmith-key
LANGCHAIN_PROJECT="Open Notebook"

Manual Installation from Source

Step 1: Install Dependencies

macOS

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install system dependencies
brew install libmagic

# Install the uv package manager
brew install uv

# Install Docker Desktop
brew install --cask docker

Ubuntu/Debian

# Update repositories and install dependencies
sudo apt update
sudo apt install -y libmagic-dev python3-dev build-essential

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

# Install and configure Docker
sudo apt install -y docker.io docker-compose-plugin
sudo systemctl start docker
sudo systemctl enable docker
sudo usermod -aG docker $USER

CentOS/RHEL/Fedora

# Install system dependencies
sudo dnf install -y file-devel python3-devel gcc

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

# Install and configure Docker
sudo dnf install -y docker docker-compose
sudo systemctl start docker
sudo systemctl enable docker
sudo usermod -aG docker $USER

Step 2: Build the Project

1. Clone the Repository

git clone https://github.com/lfnovo/open-notebook.git
cd open-notebook

2. Configure the Environment

cp .env.example .env
nano .env  # Enter your API keys

3. Install Python Packages

uv sync
uv pip install python-magic

4. Initialize the Database

make database
# Wait approximately 10 seconds for initialization

5. Launch the Application

make start-all

This command starts the following services:

• SurrealDB (Port 8000)
• FastAPI Backend (Port 5055)
• Background Task Worker
• Streamlit UI (Port 8502)

Optional: Run Services Individually

# Separate terminals
make database
make api
make worker
make run

Docker Deployment

Option 1: Single-Container (Recommended for Personal Use)

Ideal for individual users or lightweight hosting platforms like PikaPods.

1. Setup Directory

mkdir open-notebook
cd open-notebook

2. Create the Compose File

cat > docker-compose.yml << 'EOF'
services:
  open_notebook:
    image: lfnovo/open_notebook:latest-single
    ports:
      - "8502:8502"
      - "5055:5055"
    env_file:
      - ./docker.env
    pull_policy: always
    volumes:
      - ./notebook_data:/app/data
      - ./surreal_single_data:/mydata
    restart: always
EOF

3. Create the Environment File

cat > docker.env << 'EOF'
# Required AI Provider Key
OPENAI_API_KEY=your-openai-key

# Database Configuration (Defaults)
SURREAL_ADDRESS=localhost
SURREAL_PORT=8000
SURREAL_USER=root
SURREAL_PASS=root
SURREAL_NAMESPACE=open_notebook
SURREAL_DATABASE=production

# Optional Password
# OPEN_NOTEBOOK_PASSWORD=your_secure_password
EOF

4. Start the Container

docker compose up -d

Option 2: Multi-Container Setup (Production)

Designed for higher scalability.

1. Download Configuration

curl -O https://raw.githubusercontent.com/lfnovo/open-notebook/main/docker-compose.yml
curl -o docker.env https://raw.githubusercontent.com/lfnovo/open-notebook/main/.env.example

2. Configure and Launch

nano docker.env
docker compose --profile multi up -d

Common Docker Commands

# View container status
docker compose ps

# Monitor logs
docker compose logs -f

# Shut down all services
docker compose down

# Update and restart
docker compose pull
docker compose up -d

Post-Installation: Model Configuration

After logging in, you can fine-tune your model selections via the UI.

1. Access Settings

• Open http://localhost:8502.
• Navigate to the gear icon and select Models.

2. Select Models by Task

Language Models (Chat & Generation)

• Cost-Efficient: gpt-4o-mini (OpenAI), deepseek-chat (DeepSeek), or gemini-2.0-flash (Google).
• High Performance: gpt-4o (OpenAI), claude-3.5-sonnet (Anthropic), or grok-3 (xAI).

Embedding Models (Search)

• text-embedding-3-small (OpenAI) or text-embedding-004 (Google).

Text-to-Speech (Audio)

• eleven_turbo_v2_5 (ElevenLabs) for premium quality or tts-1 (OpenAI) for reliability.

Speech-to-Text (Transcription)

• whisper-1 (OpenAI) or scribe_v1 (ElevenLabs).

3. Setup Samples

• Personal Research: gpt-4o-mini, text-embedding-3-small, tts-1.
• High-Performance: claude-3.5-sonnet, text-embedding-004, eleven_turbo_v2_5.

Verifying the Installation

1. Health Checks

Check service status using make status (Source) or docker compose ps (Docker). You can also verify individual ports:

• Database: curl http://localhost:8000/health
• API: curl http://localhost:5055/health

2. Functional Test

• Create a new notebook titled "System Test."
• Add a text source containing a few sentences.
• Use the Chat tab to ask a question about the source. A coherent response confirms that the API, database, and AI provider are correctly linked.

Security Considerations

• Password Protection: For remote deployments, always set OPEN_NOTEBOOK_PASSWORD.
• API Auth: Once a password is set, all API calls require an Authorization: Bearer <password> header.
• Hardening: Use a reverse proxy (like Nginx) for HTTPS and restrict external access using firewall rules.

Troubleshooting

• Port Conflict: If port 8502 is busy, use lsof -i :8502 to find and terminate the conflicting process.
• Missing libmagic: This error usually occurs on Linux or macOS when the system-level magic library is absent. Install it using apt or brew as shown in the prerequisites.
• Database Connection Failure: Ensure SurrealDB has finished its initialization (usually 5–10 seconds) before starting the API or UI.
• Persistence Issues: If data is lost on restart, check that your Docker volume mounts are correctly defined in the docker-compose.yml and that the host directory has write permissions.