How to Set Up Open Notebook Locally: Complete Docker Installation Guide

Deploy Open Notebook locally using Docker Compose by configuring the SurrealDB service and Open Notebook container with a custom encryption key, then accessing the UI at localhost:8502 to begin private research.

Open Notebook is a privacy-first research assistant built by lfnovo/open-notebook that combines a Next.js frontend, FastAPI backend, and SurrealDB database. To set up Open Notebook locally, you only need Docker Desktop and the provided [docker-compose.yml](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml) configuration, which orchestrates all three tiers of the application architecture.

Architecture Overview

Open Notebook follows a modular three-tier design. The Frontend tier runs a Next.js 16/React 19 interface that communicates with the backend over HTTP. The API tier consists of a FastAPI server that orchestrates LangGraph workflows and manages AI provider selection via the Esperanto library. The Database tier uses SurrealDB to store notebooks, sources, notes, embeddings, and graph relationships.

Prerequisites

• Docker Desktop installed and running (Docker Engine 20.10.0+ recommended)
• 4GB of available RAM for the container stack
• (Optional) Git for cloning the repository

Step-by-Step Local Setup

Download the Docker Compose Configuration

Create a project directory and save the official docker-compose.yml file. The configuration defines two services: surrealdb for persistent data storage and open_notebook for the application server and UI.

services:
  surrealdb:
    image: surrealdb/surrealdb:v2
    command: start --log info --user root --pass root rocksdb:/mydata/mydatabase.db
    ports: ["8000:8000"]
    volumes: ["./surreal_data:/mydata"]

  open_notebook:
    image: lfnovo/open_notebook:v1-latest
    ports: ["8502:8502", "5055:5055"]
    environment:
      - OPEN_NOTEBOOK_ENCRYPTION_KEY=my-secret-key
      - SURREAL_URL=ws://surrealdb:8000/rpc
      - SURREAL_USER=root
      - SURREAL_PASSWORD=root
      - SURREAL_NAMESPACE=open_notebook
      - SURREAL_DATABASE=open_notebook
    volumes: ["./notebook_data:/app/data"]
    depends_on: [surrealdb]

Configure Encryption Keys and Environment Variables

Before starting the services, you must set the OPEN_NOTEBOOK_ENCRYPTION_KEY environment variable in the compose file. This key encrypts sensitive data in the database. Refer to .env.example for the complete list of configurable variables, including database credentials and API endpoints.

Launch the Container Stack

Execute the following command in your project directory to start the stack in detached mode:

docker compose up -d

This command initializes the SurrealDB instance and the Open Notebook service. The [api/main.py](https://github.com/lfnovo/open-notebook/blob/main/api/main.py) entry point registers all routers and enables CORS for the FastAPI application.

Access the Web Interface

Once containers are healthy (approximately 15 seconds), navigate to http://localhost:8502 to access the Streamlit-based user interface. The API documentation is available at http://localhost:5055/docs.

Configure AI Model Providers

In the UI, navigate to Models → + Add Configuration to add your AI provider credentials. The system supports OpenAI, Anthropic, and local models through the [open_notebook/ai/model_manager.py](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/ai/model_manager.py) abstraction layer.

Alternative Setup for Local LLMs

For completely offline operation without external API calls, use the Ollama configuration file located at [examples/docker-compose-ollama.yml](https://github.com/lfnovo/open-notebook/blob/main/examples/docker-compose-ollama.yml). This setup includes an Ollama service alongside the standard stack, allowing you to use local LLMs like Llama 2 or Mistral for text generation and embeddings.

Programmatic API Configuration

You can configure models and manage notebooks programmatically via the REST API. The FastAPI server exposes endpoints for source ingestion, note creation, and chat workflows defined in open_notebook/graphs/.

Add a model using cURL:

curl -X POST http://localhost:5055/models \
  -H "Content-Type: application/json" \
  -d '{
        "provider": "openai",
        "api_key": "sk-…",
        "model_name": "gpt-4o-mini",
        "max_context": 8192
      }'

Add a model using Python:

import httpx

client = httpx.AsyncClient(base_url="http://localhost:5055")
await client.post("/models", json={
    "provider": "anthropic",
    "api_key": "my-anthropic-key",
    "model_name": "claude-3-5-sonnet",
    "max_context": 100_000,
})

Summary

• Open Notebook requires Docker Desktop to run the three-tier architecture locally
• The docker-compose.yml file configures SurrealDB and the Open Notebook service with proper networking and volumes
• You must set OPEN_NOTEBOOK_ENCRYPTION_KEY before starting the containers for data security
• Access the UI at localhost:8502 and the API at localhost:5055 after launching the stack
• Support for local AI models is available via the Ollama compose configuration

Frequently Asked Questions

What ports need to be open for local Open Notebook?

Open Notebook requires ports 8502 for the web interface and 5055 for the FastAPI backend. If you are accessing SurrealDB directly from external tools, port 8000 must also be available. These are configured in the [docker-compose.yml](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml) service definitions.

Can I use a local LLM instead of OpenAI or Anthropic?

Yes, you can run completely local AI models using the [examples/docker-compose-ollama.yml](https://github.com/lfnovo/open-notebook/blob/main/examples/docker-compose-ollama.yml) configuration. This includes an Ollama container that provides local LLM capabilities for text generation and embeddings without sending data to external APIs.

Where is data stored when running Open Notebook locally?

Data persists in two Docker volumes mapped to your host filesystem: ./surreal_data for the SurrealDB database files and ./notebook_data for application data. The SurrealDB container uses RocksDB as the underlying storage engine via the command defined in the compose file.

How do I reset the database in my local setup?

To reset the database, stop the containers with docker compose down, then delete the ./surreal_data and ./notebook_data directories from your project folder. When you restart the stack with docker compose up -d, the system will initialize fresh database instances.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}