How to Build Open-Notebook From Source: A Complete Developer Guide

To build open-notebook from source, clone the repository, install Python dependencies using uv sync and Node dependencies with npm install, configure your .env files, then run make start-all to launch the full stack locally.

Open-notebook is a three-tier application comprising a Next.js frontend, a FastAPI backend, and a SurrealDB graph database. Building from source requires setting up both Python and Node environments, configuring API keys, and using the provided Makefile to orchestrate services. This guide references the actual source files in the lfnovo/open-notebook repository to ensure you follow the exact implementation used by the maintainers.

Prerequisites

Before you begin, ensure you have the following tools installed:

• UV: A fast Python package manager (used in pyproject.toml for dependency resolution)
• Node.js: Required for the Next.js frontend (see frontend/package.json for version requirements)
• Docker: Needed to run SurrealDB and for containerized build modes
• Git: To clone the repository

Step-by-Step Build Process

Clone and Configure Environment

First, clone the repository and prepare the configuration files:

git clone https://github.com/lfnovo/open-notebook.git
cd open-notebook
cp .env.example .env
cp .env.example docker.env

The .env file supplies configuration to the API and worker processes, while docker.env is used by Docker Compose services. At minimum, you must configure the SurrealDB connection string and at least one AI provider API key (OpenAI, Anthropic, or Google) as documented in the environment variables section.

Install Dependencies

Open-notebook uses UV for Python dependency management. Run the following command in the repository root:

uv sync

This command reads the pyproject.toml file and installs exact locked versions into a virtual environment. Next, install the frontend dependencies:

cd frontend
npm install
cd ..

The frontend/ directory follows standard Next.js conventions, and npm install will fetch all React components and build tools specified in package.json.

Select Build Mode

The Makefile provides several distinct modes for building and running the application. Choose the mode that matches your use case:

• Local Development (make start-all): Fastest iteration for daily development
• Docker Compose (make dev or make full): Containerized setup for CI or production-like testing
• Production Build (make docker-build-local): Single-platform image for local testing

Build Modes Explained

Local Development Mode (Recommended)

For rapid iteration, use the make start-all command, which starts all services natively except for SurrealDB:

make start-all

This command executes the following sequence from the Makefile (lines 55-73):

1. docker compose -f docker-compose.dev.yml up -d surrealdb – Starts the SurrealDB graph database in the background
2. uv run run_api.py & – Launches the FastAPI backend on port 5055 using the Python virtual environment
3. uv run --env-file .env surreal-commands-worker --import-modules commands & – Starts the asynchronous background worker that processes LangGraph workflows
4. cd frontend && npm run dev – Serves the Next.js frontend at http://localhost:3000

This mode provides hot-reloading for both the frontend and backend while keeping the database persistent in Docker.

Docker Compose Mode

To verify the containerized setup or test production configurations, use the Docker Compose targets:

make dev      # Development compose with volume mounts

make full     # Full production-like stack

The make full command executes docker compose -f docker-compose.full.yml up --build, which builds images for all services and starts the complete stack mirroring a production deployment. This mode is ideal for CI pipelines or testing the exact container configuration before release.

Production Image Build

To build a production-ready image for your local platform only:

make docker-build-local

This command builds the image defined in Dockerfile.single (or Dockerfile) and tags it as lfnovo/open_notebook:local. For multi-platform releases (amd64 and arm64) that push to Docker Hub and GitHub Container Registry, maintainers use make docker-release, which handles the complex buildx configuration and tagging scheme.

Verification and Testing

Once the services are running, verify the installation:

• API Health: Visit http://localhost:5055/health or http://localhost:5055/docs for the Swagger UI
• Frontend: Open http://localhost:3000 to access the React UI
• Service Status: Run make status to check the health of each containerized service

To run the automated test suite:

uv run pytest tests/

The test suite covers domain models, API endpoints, LangGraph workflows, and embedding functionality. For cleanup when finished:

make stop-all

Summary

• Open-notebook requires three components: a Next.js frontend, FastAPI backend, and SurrealDB database.
• Use uv sync to install Python dependencies and npm install in the frontend/ directory for Node packages.
• Copy .env.example to .env and configure at least one AI provider key and database credentials.
• make start-all is the fastest way to begin development, starting all services locally with hot-reloading.
• make full provides a production-like Docker environment for testing containerized deployments.
• Key files to reference: Makefile (orchestration), pyproject.toml (Python dependencies), docker-compose.dev.yml (services), and api/main.py (FastAPI entry point).

Frequently Asked Questions

What is the fastest way to build open-notebook for local development?

The fastest approach is using make start-all after running uv sync and npm install. This command starts SurrealDB in Docker while running the FastAPI backend, background worker, and Next.js frontend natively on your machine, providing hot-reloading for code changes without rebuilding containers.

Do I need Docker to build open-notebook from source?

You need Docker only for the SurrealDB database and optional containerized builds. The make start-all command uses Docker solely to run SurrealDB, while the Python backend and Node frontend run directly on your host system. However, for a fully containerized build, Docker is required.

Where are the API endpoints defined in the source code?

The FastAPI application is initialized in api/main.py, which registers routers, configures CORS middleware, and sets up exception handlers. The individual API routes are organized in the api/ directory, with the main entry point handling application startup and shutdown events.

Can I build open-notebook without using the Makefile?

Yes, though the Makefile automates the process. You can manually start SurrealDB with docker compose -f docker-compose.dev.yml up surrealdb, then run uv run run_api.py for the backend, uv run surreal-commands-worker for the worker, and npm run dev in the frontend/ directory. The Makefile simply orchestrates these commands in the correct order with proper environment variables.

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