How to Set Up a Local Development Environment for Open Notebook

To set up a local development environment for open-notebook, clone the repository, copy the environment templates from .env.example, install dependencies with uv sync, and run make start-all to launch the SurrealDB database, FastAPI backend, and Next.js frontend with hot-reload enabled.

Open Notebook is a three-tier application that combines a React/Next.js frontend, a FastAPI Python backend, and a SurrealDB graph database. When you set up a local development environment for open-notebook, you run each component natively to enable instant code reloads and direct log access. The repository provides a Makefile and README.dev.md that automate the bootstrap process.

Clone the Repository and Configure Environment

Begin by cloning the repository and navigating to the project root:

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

Create the required environment files by copying the template. According to README.dev.md (lines 12-15), you need both .env for local development and docker.env for containerized workflows:

cp .env.example .env
cp .env.example docker.env

Edit .env to configure your SurrealDB connection and API keys. The file must define variables such as:

SURREAL_URL=ws://localhost:8000
SURREAL_USER=root
SURREAL_PASS=root
SURREAL_DB=open_notebook
SURREAL_NS=production
OPENAI_API_KEY=sk-...

Install Python Dependencies with uv

Open Notebook uses uv as its built-in package manager. As documented in README.dev.md (lines 16-18), install all dependencies by running:

uv sync

This command installs the FastAPI backend, the core open_notebook library, LangGraph workflows, and the SurrealDB driver into a virtual environment managed by uv.

Start the Full Development Stack

Launch all services simultaneously using the command from README.dev.md (lines 20-27):

make start-all

This command starts four processes:

• SurrealDB on port 8000 (inside a Docker container)
• FastAPI backend on port 5055 (started via uvicorn in api/main.py)
• Background worker for async tasks
• Next.js frontend on port 3000

The services are configured for hot-reload. When you edit TypeScript files in frontend/ or Python files in api/ and open_notebook/, the changes reflect immediately. The frontend communicates with the API at http://localhost:5055 using TanStack Query for data fetching, while the backend uses the SurrealDB abstraction layer defined in open_notebook/database/repository.py.

Access the application at http://localhost:3000 and view the interactive API documentation at http://localhost:5055/docs.

Development Workflow and Debugging

For day-to-day iteration, use the Makefile helpers defined in the repository root. Check service status with:

make status

Stop all services gracefully:

make stop-all

To debug only the FastAPI backend without the frontend or worker, run:

make api

Alternatively, start the API server manually with:

uv run python -m api.main

This launches the FastAPI application defined in api/main.py, which registers routers from api/models_service.py, api/search_service.py, and other service modules. The async SurrealDB driver connects automatically using the credentials from your .env file.

To test LangGraph workflows directly, open a Python REPL and import from the core library:

from open_notebook.graphs.source import source_graph

await source_graph.ainvoke(
    {"url": "https://example.com/article.pdf"},
    config={"recursion_limit": 2}
)

The graph definition resides in open_notebook/graphs/source.py and handles source ingestion, embedding, and storage.

Alternative Development Methods

The Makefile provides additional targets for different validation scenarios:

• make dev or make full: Runs the entire stack via Docker Compose using docker-compose.yml. Use this to verify containerization behavior or simulate CI environments.
• make docker-build-local: Builds a production Docker image locally. Use this to validate Dockerfile changes before publishing.

These commands complement the hot-reload workflow but are not required for daily development.

Testing Your Changes

Run the test suite using pytest through uv:

uv run pytest tests/

This executes unit and integration tests against the codebase, including tests for the database repository layer and API endpoints.

Summary

• Clone the repository and copy .env.example to .env and docker.env to configure your local environment.
• Install dependencies with uv sync, which leverages the uv package manager bundled with the project.
• Launch services using make start-all to run SurrealDB (port 8000), FastAPI (port 5055), the background worker, and the Next.js frontend (port 3000) with hot-reload.
• Debug specifically by running make api to start only the FastAPI backend from api/main.py.
• Validate containerization with make dev or make full when you need to test Docker Compose configurations.

Frequently Asked Questions

Do I need Docker installed for local development?

Yes. Even when running the application natively for hot-reload development, SurrealDB requires a Docker container as specified in the docker-compose.yml configuration. The make start-all command handles this automatically, launching SurrealDB on port 8000 while keeping the Python and Node.js processes on your host machine.

How do I run only the backend API for debugging?

Execute make api from the repository root, or manually start the server with uv run python -m api.main. This launches only the FastAPI application defined in api/main.py on port 5055, allowing you to debug Python code without starting the frontend or background worker. The API will still connect to SurrealDB on port 8000 if it is running.

Where are the database migration scripts located?

Migration scripts reside in the migrations/ directory at the repository root. These are applied automatically when the API server starts, as implemented in the startup sequence of api/main.py. The migrations configure the SurrealDB schema and initial data structures required by the open_notebook/database/repository.py abstraction layer.

What is the difference between make start-all and make dev?

make start-all runs the database in Docker but executes the Python FastAPI backend, background worker, and Node.js frontend directly on your host machine. This provides the fastest iteration speed with hot-reload. In contrast, make dev (or make full) runs the entire stack inside Docker containers via docker-compose.yml, which is useful for verifying containerization or testing production-like environments where host filesystem mounts are not available.

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