# How to Set Up a Local Development Environment for Open Notebook

> Quickly set up your local development environment for lfnovo/open-notebook. Clone, install dependencies, and start the SurrealDB, FastAPI, and Next.js services with a single command.

- Repository: [Luis Novo/open-notebook](https://github.com/lfnovo/open-notebook)
- Tags: getting-started
- Published: 2026-06-26

---

**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`](https://github.com/lfnovo/open-notebook/blob/main/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:

```bash
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`](https://github.com/lfnovo/open-notebook/blob/main/README.dev.md) (lines 12-15), you need both `.env` for local development and `docker.env` for containerized workflows:

```bash
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:

```text
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`](https://github.com/lfnovo/open-notebook/blob/main/README.dev.md) (lines 16-18), install all dependencies by running:

```bash
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`](https://github.com/lfnovo/open-notebook/blob/main/README.dev.md) (lines 20-27):

```bash
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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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:

```bash
make status

```

Stop all services gracefully:

```bash
make stop-all

```

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

```bash
make api

```

Alternatively, start the API server manually with:

```bash
uv run python -m api.main

```

This launches the FastAPI application defined in [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py), which registers routers from [`api/models_service.py`](https://github.com/lfnovo/open-notebook/blob/main/api/models_service.py), [`api/search_service.py`](https://github.com/lfnovo/open-notebook/blob/main/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:

```python
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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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:

```bash
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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py). The migrations configure the SurrealDB schema and initial data structures required by the [`open_notebook/database/repository.py`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml), which is useful for verifying containerization or testing production-like environments where host filesystem mounts are not available.