How to Build and Run Open Notebook on macOS, Linux, and Windows

You can build and run Open Notebook either from source using uv and Node.js for development, or via Docker Compose for a containerized deployment, with specific configuration adjustments required for Windows environments.

Open Notebook is a three-tier research application by lfnovo/open-notebook that combines a FastAPI backend, Next.js frontend, and SurrealDB graph database. Depending on your operating system and whether you need to modify the source code, you can choose between a developer-friendly source installation or a containerized Docker deployment. This guide covers both methods for macOS, Linux, and Windows, including platform-specific fixes found in the official documentation.

Architecture Overview

The application stack consists of three distinct services that must run simultaneously:

• Frontend: Next.js 16 (React 19) located in the frontend/ directory, typically running on port 3000 (or 8502 in Docker Compose)
• API: FastAPI 0.104+ located in api/ and open_notebook/, running on port 5055
• Database: SurrealDB WebSocket interface on port 8000

The frontend communicates with the FastAPI backend over HTTP, which persists data to SurrealDB via the WebSocket URL defined in your .env file (SURREAL_URL). All three services can be started independently, but the repository provides a make start-all command in the Makefile that orchestrates the correct startup sequence.

Prerequisites by Operating System

Before building, ensure your system meets these requirements:

macOS and Linux

• Python 3.11+ and uv (the Python package manager)
• Node.js 18+
• Docker Desktop (for SurrealDB) or Docker Engine
• Git

Install uv on macOS with: brew install uv or via the official installer: curl -LsSf https://astral.sh/uv/install.sh | sh.

Windows (Docker)

• Git, Python 3.12+, Node.js 18+, and uv
• Docker Desktop for Windows
• Install via: winget install Git.Git OpenJS.NodeJS and pip install uv

Windows (Native, No Docker)

• Git, Python 3.12+, Node.js 18+, and uv
• SurrealDB installed via Scoop: scoop install surrealdb
• See docs/1-INSTALLATION/windows-native.md for the complete checklist.

Building from Source

Running from source is ideal for developers who need to modify the FastAPI backend or Next.js frontend. This method uses uv for Python dependency management and npm for Node.js packages.

Step-by-Step Setup

1. Clone the repository and install Python dependencies:

git clone https://github.com/lfnovo/open-notebook.git
cd open-notebook
uv sync
uv pip install python-magic  # Required on some Linux distributions

2. Configure the environment:

cp .env.example .env

# Edit .env to set:

# - OPEN_NOTEBOOK_ENCRYPTION_KEY (generate a secure random string)

# - SURREAL_URL (use ws://127.0.0.1:8000/rpc on Windows)

3. Start SurrealDB using the Make target or Docker directly:

make database  # Runs: docker compose up -d surrealdb

4. Launch the API backend:

make api  # Runs: uv run --env-file .env run_api.py

5. Start the background worker (required for async jobs like podcast generation):

make worker-start

6. Run the Next.js frontend:

make frontend  # Runs: cd frontend && npm run dev

Access the application at http://localhost:3000 (or http://127.0.0.1:3000 on Windows).

Using the Makefile

The Makefile at the repository root provides convenience targets that handle the virtual environment and working directories automatically. According to the source code in Makefile at lines 55-72, the start-all target launches the database, API, background worker, and frontend in the correct order:

make start-all

This single command is equivalent to running the database, API, worker, and frontend startup commands sequentially.

Docker Compose Installation

For users who prefer containerization or want to avoid managing Python and Node.js environments locally, Docker Compose provides the simplest cross-platform solution.

1. Download the official compose file:

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

2. Edit the encryption key (line 31 in the file):

- OPEN_NOTEBOOK_ENCRYPTION_KEY=change-me-to-a-secret-string

3. Start all services:

docker compose up -d

4. Access the services:
   • Frontend: http://localhost:8502
   • API documentation: http://localhost:5055/docs
   • SurrealDB: ws://localhost:8000/rpc

The Docker Compose configuration automatically handles networking between the three tiers. On Windows, Docker Desktop automatically resolves host.docker.internal without requiring additional host entries.

Native Windows Installation

If Docker is unavailable (e.g., on Windows ARM64 or systems without Hyper-V), follow the native Windows guide in docs/1-INSTALLATION/windows-native.md.

Critical Windows-specific configuration steps include:

1. Update the database URL in .env to use IP address instead of hostname:

   
   SURREAL_URL="ws://127.0.0.1:8000/rpc"
   

   This change is documented in docs/1-INSTALLATION/windows-native.md at lines 46-51 and prevents "database health check timed out" errors caused by localhost resolution issues.

2. Create a batch launcher (start-open-notebook.bat) that sets the ROOT and DATA_FOLDER environment variables, then launches components using uv run:

set ROOT=%~dp0
set DATA_FOLDER=C:\open-notebook-data
uv run --env-file .env python -m surreal_commands.cli.worker --import-modules commands
uv run --env-file .env run_api.py
cd frontend && npm install && npm run dev

3. Use uv run exclusively rather than activating virtual environments manually. As noted in docs/1-INSTALLATION/windows-native.md at lines 91-99, invoking Python directly without uv run causes ModuleNotFoundError because the system Python lacks the project's dependencies.

Troubleshooting Common Issues

Symptom	Cause	Solution
ModuleNotFoundError: No module named 'langgraph.checkpoint.sqlite'	System Python used instead of uv virtualenv	Prefix all Python commands with uv run (see docs/1-INSTALLATION/windows-native.md lines 91-99)
Database health check timeout	.env uses localhost while SurrealDB binds to 127.0.0.1	Change SURREAL_URL to ws://127.0.0.1:8000/rpc (see docs/1-INSTALLATION/windows-native.md lines 11-21)
Worker fails to locate commands module	PYTHONPATH not set in Windows batch script	Set PYTHONPATH to the project root before launching the worker (see docs/1-INSTALLATION/windows-native.md lines 31-38)
Docker on Linux cannot reach host.docker.internal	Linux Docker lacks this hostname by default	Add extra_hosts: - "host.docker.internal:host-gateway" to docker-compose.yml

Summary

• Open Notebook consists of a FastAPI backend (port 5055), Next.js frontend (port 3000/8502), and SurrealDB (port 8000).
• Source installation requires uv, Node.js, and Docker for the database; use make start-all to orchestrate startup.
• Docker Compose offers the simplest cross-platform deployment with pre-configured networking.
• Windows users must change SURREAL_URL to ws://127.0.0.1:8000/rpc and use uv run for all Python commands.
• Linux users running Docker may need to add extra_hosts to resolve host.docker.internal when connecting to host services like Ollama.

Frequently Asked Questions

Can I run Open Notebook on Windows without Docker?

Yes. The repository includes a native Windows installation guide at docs/1-INSTALLATION/windows-native.md that uses uv for Python package management and Scoop to install SurrealDB directly on your system. You must modify the .env file to use 127.0.0.1 instead of localhost for the database connection and create a batch file to set environment variables before launching the services.

What is the difference between running from source and using Docker Compose?

Running from source is intended for developers who need to modify the FastAPI backend (api/) or Next.js frontend (frontend/). It requires installing Python, Node.js, and uv locally, and launches the frontend on port 3000. Docker Compose is a pre-configured, production-ready setup that bundles all three services into containers, exposes the frontend on port 8502, and requires no local runtime installations beyond Docker itself.

Why does the database connection fail on Windows with "localhost"?

Windows networking stacks often resolve localhost differently than 127.0.0.1, causing the SurrealDB WebSocket connection to fail. According to the Windows native installation documentation, you must explicitly set SURREAL_URL="ws://127.0.0.1:8000/rpc" in your .env file to ensure the FastAPI backend can reach the database.

How do I update Open Notebook to the latest version?

For source installations, run git pull to fetch the latest code, then uv sync to update Python dependencies, and cd frontend && npm install to refresh Node.js modules. For Docker Compose deployments, pull the updated docker-compose.yml file and run docker compose up -d to recreate the containers with the latest images.

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