# How to Set Up a Development Environment for Open Notebook > Set up your Open Notebook development environment. Install Python, SurrealDB, and Node.js, sync dependencies, configure .env, and start services. - Repository: [Luis Novo/open-notebook](https://github.com/lfnovo/open-notebook) - Tags: how-to-guide - Published: 2026-06-13 --- **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`](https://github.com/lfnovo/open-notebook/blob/main/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: ```bash 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`](https://github.com/lfnovo/open-notebook/blob/main/CLAUDE.md) file. Install Python dependencies using the recommended `uv` tool: ```bash uv sync ``` This command creates an isolated virtual environment, installs the project in editable mode, and resolves all transitive dependencies listed in [`pyproject.toml`](https://github.com/lfnovo/open-notebook/blob/main/pyproject.toml). If you do not have `uv` installed, use the fallback method: ```bash pip install -e . ``` ## Configure Environment Variables Copy the example environment file and edit it to match your local setup: ```bash cp .env.example .env ``` Edit `.env` to configure the database connection and security settings. The following variables are required: ```dotenv # 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`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/config.py) reads these values at runtime. ## Start SurrealDB Launch SurrealDB using Docker on port 8000: ```bash 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: ```bash 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: ```bash uv run --env-file .env uvicorn api.main:app --host 0.0.0.0 --port 5055 ``` For convenience, use the Make target: ```bash make api ``` The [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/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: ```bash 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: ```bash 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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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.