How to Deploy Open Notebook: Docker Compose and Source Installation Guide

Deploy Open Notebook by running its official docker-compose.yml file, which orchestrates the Next.js frontend, FastAPI API, and SurrealDB database in connected containers with one command.

Open Notebook is an open-source, privacy-first AI research assistant maintained in the lfnovo/open-notebook repository. Because it is built as a three-tier application, the project provides production-ready Docker Compose configurations that handle networking, persistent volumes, and environment variables automatically. You can also deploy open-notebook from source if you need to modify the codebase or contribute to the project.

Architecture Overview

The application stack consists of three distinct layers defined in the repository's docker-compose.yml.

• Frontend: Next.js 16 and React 19 serve the notebook UI, chat interface, and podcast generation tools from the frontend/ directory, mapped to port 8502 in the container configuration.
• API: FastAPI 0.104+, initialized in api/main.py, exposes a REST API on port 5055 and coordinates LangGraph workflows, AI provider selection, and database queries.
• Database: SurrealDB runs as a graph and vector database inside its own service, persisting data to the ./surreal_data volume while the API mounts ./notebook_data for application files.

When you deploy open-notebook via Docker Compose, these services communicate over an internal Docker network and rely on declared volumes for state persistence.

Deploy Open Notebook with Docker Compose (Recommended)

This method is the fastest way to run a production-grade instance on any operating system that supports Docker Desktop. For a complete installation checklist, you can also reference docs/1-INSTALLATION/index.md in the repository root.

Prerequisites

Install Docker Desktop on your machine. This provides the docker compose CLI required to process the multi-service definition.

Configure the Docker Compose File

Copy the official docker-compose.yml from the root of the lfnovo/open-notebook repository into a local directory. The file defines the surrealdb service and the open_notebook service with the following structure:

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=change-me-to-a-secret-string
      - 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]

Update the OPEN_NOTEBOOK_ENCRYPTION_KEY environment variable with a strong secret string before starting the stack.

Start the Services

Run the following command from the same directory as your docker-compose.yml:

docker compose up -d

This pulls the images and creates the containers in detached mode. To observe the API startup and automatic migrations, tail the logs:

docker compose logs -f open_notebook

Wait approximately 20 seconds, then navigate to http://localhost:8502 to access the web interface.

Complete Initial Setup

After you deploy open-notebook, the UI will prompt you to configure AI provider credentials. You can add keys for OpenAI, Anthropic, Ollama, or other supported backends directly in the interface. Alternatively, programmatically add a credential via the API running on http://localhost:5055:

curl -X POST http://localhost:5055/api/credentials \
  -H "Content-Type: application/json" \
  -d '{
        "provider": "openai",
        "api_key": "sk-····",
        "name": "My OpenAI"
      }'

Deploy Open Notebook from Source

Use this approach if you are modifying code, running tests, or contributing to the lfnovo/open-notebook project.

Install Development Dependencies

You need Python 3.11+, Node.js 18+, and the uv package manager installed on your workstation.

Clone and Build

Execute these commands in your terminal:

git clone https://github.com/lfnovo/open-notebook.git
cd open-notebook
uv sync
npm install --prefix frontend

The uv sync command installs Python dependencies using pyproject.toml, while npm install resolves the frontend packages.

Launch the Application Stack

Run the orchestration command:

make start-all

The Makefile starts SurrealDB, launches the FastAPI server via uv run uvicorn api.main:app --reload, and runs the Next.js development server. In this mode, the API is available at http://localhost:5055 and the UI at http://localhost:8502.

Verify Deployment and Run Your First Workflow

Once the containers or source processes are running, confirm API connectivity by creating a notebook:

curl -X POST http://localhost:5055/api/notebooks \
  -H "Content-Type: application/json" \
  -d '{"title":"Research on AI"}'

You can also trigger an ingestion workflow programmatically. The following Python script imports source_graph from open_notebook.graphs.source and processes a document URL:

import asyncio
from open_notebook.graphs.source import source_graph

async def ingest(url: str):
    await source_graph.ainvoke({"url": url})

asyncio.run(ingest("https://arxiv.org/pdf/2302.12345.pdf"))

For fully offline AI inference, refer to examples/docker-compose-ollama.yml in the repository to integrate a local Ollama container.

Summary

• Docker Compose is the recommended way to deploy open-notebook for both local and production use, requiring only a single docker compose up -d command after configuring OPEN_NOTEBOOK_ENCRYPTION_KEY in the official docker-compose.yml.
• The stack includes a Next.js frontend on port 8502, a FastAPI backend on port 5055, and SurrealDB on port 8000, connected via Docker networking and persistent volumes.
• Developers can deploy open-notebook from source using uv sync, npm install --prefix frontend, and make start-all, which executes api/main.py with hot-reload enabled.
• Post-deployment, the REST API at http://localhost:5055 exposes endpoints for credentials, notebooks, and LangGraph workflows.
• Offline deployments are supported by referencing the Ollama example compose file located at examples/docker-compose-ollama.yml.

Frequently Asked Questions

Can I deploy Open Notebook without using Docker?

Yes, but you must manage the dependencies manually. Install Python 3.11+, Node.js 18+, uv, and SurrealDB separately, then run make start-all in the cloned lfnovo/open-notebook repository to launch all processes. This path is intended for active development rather than production hosting.

What should I set for the OPEN_NOTEBOOK_ENCRYPTION_KEY variable?

Replace the placeholder change-me-to-a-secret-string in docker-compose.yml with a long, randomly generated string before you deploy open-notebook. This key is consumed by the open_notebook container to secure sensitive application data at rest.

How do I add a local LLM such as Ollama to my deployment?

Mount or link an Ollama container to the Docker network and configure the provider in the Open Notebook UI or through the API credentials endpoint at http://localhost:5055/api/credentials. The repository includes examples/docker-compose-ollama.yml, which demonstrates how to add a local model service for fully offline inference.

Is the single-container deployment still maintained?

The single-container option based on Dockerfile.single is deprecated and scheduled for removal in version 2. New installations should use the multi-service docker-compose.yml found in the root of the repository, as it provides clearer separation of concerns and reliable persistent data handling.

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