How to Set Up a Development Environment for Open Notebook

Open Notebook requires Python 3.11+, SurrealDB, and optionally Node.js 18+; clone the repository, run uv sync to install dependencies, configure a .env file with database credentials and an encryption key, then start the database, FastAPI backend, and Next.js frontend services.

Open Notebook is a full-stack application built with a FastAPI backend, SurrealDB graph database, and Next.js + React frontend. Setting up a local development environment involves configuring these three tiers to communicate via environment variables and WebSocket connections. This guide walks through the complete installation process using the modern uv package manager and Docker-based database services according to the official docs/7-DEVELOPMENT/development-setup.md.

Prerequisites

Before starting, ensure you have the following tools installed:

• Python 3.11+ – Required to run the FastAPI backend and all Python utilities.
• uv (recommended) – A fast Python package manager that handles dependency resolution, virtual environment creation, and script execution via commands like uv sync and uv run.
• SurrealDB – The graph-oriented database that stores notebooks, sources, notes, and embeddings. Install via Docker using surrealdb/surrealdb:v2 or download the binary directly.
• Docker (optional but recommended) – Provides containerized SurrealDB and simplifies the full stack setup.
• Node.js 18+ (optional) – Required only if you plan to modify the Next.js frontend.
• Git – For cloning the repository and managing branches.

Clone the Repository and Install Dependencies

Start by cloning the repository from GitHub and navigating into the project root:

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

The project follows a three-tier architecture (frontend → API → SurrealDB) as documented in the root CLAUDE.md file. Install Python dependencies using the recommended uv tool:

uv sync

This command creates an isolated virtual environment, installs the project in editable mode, and resolves all transitive dependencies listed in pyproject.toml. If you do not have uv installed, use the fallback method:

pip install -e .

Configure Environment Variables

Copy the example environment file and edit it to match your local setup:

cp .env.example .env

Edit .env to configure the database connection and security settings. The following variables are required:

# SurrealDB connection

SURREAL_URL=ws://localhost:8000/rpc
SURREAL_USER=root
SURREAL_PASSWORD=password
SURREAL_NAMESPACE=open_notebook
SURREAL_DATABASE=development

# Encryption key for AI provider credentials

OPEN_NOTEBOOK_ENCRYPTION_KEY=my-dev-secret-key

# Optional development flags

DEBUG=true
LOG_LEVEL=DEBUG

The OPEN_NOTEBOOK_ENCRYPTION_KEY is mandatory for the credential store that encrypts API keys for OpenAI, Anthropic, and other providers. The configuration loader in open_notebook/config.py reads these values at runtime.

Start SurrealDB

Launch SurrealDB using Docker on port 8000:

docker run -d --name surrealdb -p 8000:8000 \
  surrealdb/surrealdb:v2 start \
  --user root --pass password \
  --bind 0.0.0.0:8000 memory

Alternatively, use the provided Makefile target:

make database

SurrealDB exposes a WebSocket RPC endpoint at ws://localhost:8000/rpc that the API consumes for all database operations.

Launch the API Server

Start the FastAPI application using uvicorn with the environment file loaded:

uv run --env-file .env uvicorn api.main:app --host 0.0.0.0 --port 5055

For convenience, use the Make target:

make api

The api/main.py file serves as the FastAPI entry point, registering routers for notebooks, sources, chat, and search. Upon startup, it automatically applies any pending SurrealQL migrations located in the migrations/ folder. You will see log output confirming migration completion:

Running migration 001_initial_schema
Migrations completed successfully

Verify the API is running:

curl http://localhost:5055/health

# Output: {"status":"ok"}

Access the interactive API documentation at http://localhost:5055/docs.

(Optional) Start the Frontend

If you plan to work on the user interface, start the Next.js development server:

cd frontend
npm install
npm run dev

The frontend runs on http://localhost:3000 and communicates with the backend via the base URL defined in your .env file. It uses Zustand for state management, TanStack Query for data fetching, and shadcn/ui with Tailwind CSS for styling.

Verify Your Setup

Confirm all services are operational using the following checks:

• SurrealDB: curl http://localhost:8000/ returns server information.
• API Health: curl http://localhost:5055/health returns {"status":"ok"}.
• API Documentation: Browse to http://localhost:5055/docs to view the Swagger UI.
• Frontend: Visit http://localhost:3000 to see the dashboard.
• Migrations: Check API logs for "Migrations completed successfully" to confirm the schema is current.

Development Workflow Tips

Streamline your development with these repository tools:

• Pre-commit hooks – Run uv run pre-commit install to enforce linting and formatting before each commit.
• Testing – Execute uv run pytest or make test to run unit and integration tests. For coverage reports, use uv run pytest --cov=open_notebook --cov-report=html.
• Linting – Run make ruff for automatic code-style fixes and make lint for static type checking with MyPy.

Troubleshooting Common Issues

Symptom	Likely Cause	Solution
"Connection refused" from API	SurrealDB not running or incorrect SURREAL_URL	Verify docker ps shows the surrealdb container and check that .env contains ws://localhost:8000/rpc
Port 5055 or 3000 already in use	Another process occupies the port	Run lsof -i :5055 to identify the process, then kill it or change the port in the uvicorn command
Import errors when running API	Dependencies out of sync	Re-run uv sync or pip install -e . to refresh the environment
Migrations not applied	API started before SurrealDB was ready	Restart the API service after ensuring SurrealDB is fully initialized and credentials match

Summary

• Open Notebook consists of a FastAPI backend (api/main.py), SurrealDB database, and optional Next.js frontend.
• Use uv sync to install Python dependencies and create an isolated environment.
• Configure .env with SurrealDB connection strings and OPEN_NOTEBOOK_ENCRYPTION_KEY for AI credential storage.
• Start services in order: SurrealDB (port 8000), then the API (uvicorn api.main:app on port 5055), then the frontend (port 3000).
• Migrations apply automatically at API startup from the migrations/ directory.
• Use make api, make database, and make test for convenient development commands.

Frequently Asked Questions

What are the minimum Python and Node.js versions required?

Open Notebook requires Python 3.11 or higher to support the modern FastAPI backend and async features. The frontend requires Node.js 18 or higher to build the Next.js application, though you can develop API features without Node.js installed.

Why does the API fail to start with a SurrealDB connection error?

This occurs when the SURREAL_URL in .env does not match the running database endpoint or when SurrealDB hasn't finished initializing. Verify the container is running with docker ps, ensure the URL uses the WebSocket protocol (ws://localhost:8000/rpc), and confirm the username and password match the values used in the Docker run command.

How do I apply database schema changes during development?

You do not need to manually apply migrations. The API automatically executes SurrealQL scripts from the migrations/ folder when it starts up, as implemented in api/main.py. Simply restart the API service after pulling new code that includes migration files.

Can I develop without installing Node.js?

Yes. If you only need to work on the Python backend or SurrealDB schema, you can interact with the API directly using the Swagger UI at http://localhost:5055/docs or tools like curl and Postman. The frontend is optional for backend development.

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