# How to Build Open-Notebook From Source: A Complete Developer Guide > Learn to build Open-Notebook from source. Clone the repo, install dependencies, configure .env, and run make start all for a full local stack. Your developer guide awaits. - Repository: [Luis Novo/open-notebook](https://github.com/lfnovo/open-notebook) - Tags: how-to-guide - Published: 2026-06-13 --- **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`](https://github.com/lfnovo/open-notebook/blob/main/pyproject.toml) for dependency resolution) - **Node.js**: Required for the Next.js frontend (see [`frontend/package.json`](https://github.com/lfnovo/open-notebook/blob/main/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: ```bash 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: ```bash uv sync ``` This command reads the [`pyproject.toml`](https://github.com/lfnovo/open-notebook/blob/main/pyproject.toml) file and installs exact locked versions into a virtual environment. Next, install the frontend dependencies: ```bash 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`](https://github.com/lfnovo/open-notebook/blob/main/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: ```bash 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: ```bash 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: ```bash 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: ```bash uv run pytest tests/ ``` The test suite covers domain models, API endpoints, LangGraph workflows, and embedding functionality. For cleanup when finished: ```bash 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`](https://github.com/lfnovo/open-notebook/blob/main/pyproject.toml) (Python dependencies), [`docker-compose.dev.yml`](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.dev.yml) (services), and [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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.