# How to Deploy Open Notebook: Docker Compose and Source Installation Guide

> Deploy Open Notebook easily with Docker Compose. This guide shows you how to orchestrate the frontend API and database with a single command for a seamless setup.

- Repository: [Luis Novo/open-notebook](https://github.com/lfnovo/open-notebook)
- Tags: how-to-guide
- Published: 2026-06-08

---

**Deploy Open Notebook by running its official [`docker-compose.yml`](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml) file, which orchestrates the Next.js frontend, FastAPI API, and SurrealDB database in connected containers with one command.**

Open Notebook is an open-source, privacy-first AI research assistant maintained in the `lfnovo/open-notebook` repository. Because it is built as a three-tier application, the project provides production-ready Docker Compose configurations that handle networking, persistent volumes, and environment variables automatically. You can also deploy open-notebook from source if you need to modify the codebase or contribute to the project.

## Architecture Overview

The application stack consists of three distinct layers defined in the repository's [`docker-compose.yml`](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml).

- **Frontend:** Next.js 16 and React 19 serve the notebook UI, chat interface, and podcast generation tools from the `frontend/` directory, mapped to port `8502` in the container configuration.
- **API:** FastAPI 0.104+, initialized in [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py), exposes a REST API on port `5055` and coordinates LangGraph workflows, AI provider selection, and database queries.
- **Database:** SurrealDB runs as a graph and vector database inside its own service, persisting data to the `./surreal_data` volume while the API mounts `./notebook_data` for application files.

When you deploy open-notebook via Docker Compose, these services communicate over an internal Docker network and rely on declared volumes for state persistence.

## Deploy Open Notebook with Docker Compose (Recommended)

This method is the fastest way to run a production-grade instance on any operating system that supports Docker Desktop. For a complete installation checklist, you can also reference [`docs/1-INSTALLATION/index.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/1-INSTALLATION/index.md) in the repository root.

### Prerequisites

Install Docker Desktop on your machine. This provides the `docker compose` CLI required to process the multi-service definition.

### Configure the Docker Compose File

Copy the official [`docker-compose.yml`](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml) from the root of the `lfnovo/open-notebook` repository into a local directory. The file defines the `surrealdb` service and the `open_notebook` service with the following structure:

```yaml
services:
  surrealdb:
    image: surrealdb/surrealdb:v2
    command: start --log info --user root --pass root rocksdb:/mydata/mydatabase.db
    ports: ["8000:8000"]
    volumes: ["./surreal_data:/mydata"]
  open_notebook:
    image: lfnovo/open_notebook:v1-latest
    ports: ["8502:8502", "5055:5055"]
    environment:
      - OPEN_NOTEBOOK_ENCRYPTION_KEY=change-me-to-a-secret-string
      - SURREAL_URL=ws://surrealdb:8000/rpc
      - SURREAL_USER=root
      - SURREAL_PASSWORD=root
      - SURREAL_NAMESPACE=open_notebook
      - SURREAL_DATABASE=open_notebook
    volumes: ["./notebook_data:/app/data"]
    depends_on: [surrealdb]

```

Update the `OPEN_NOTEBOOK_ENCRYPTION_KEY` environment variable with a strong secret string before starting the stack.

### Start the Services

Run the following command from the same directory as your [`docker-compose.yml`](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml):

```bash
docker compose up -d

```

This pulls the images and creates the containers in detached mode. To observe the API startup and automatic migrations, tail the logs:

```bash
docker compose logs -f open_notebook

```

Wait approximately 20 seconds, then navigate to `http://localhost:8502` to access the web interface.

### Complete Initial Setup

After you deploy open-notebook, the UI will prompt you to configure AI provider credentials. You can add keys for OpenAI, Anthropic, Ollama, or other supported backends directly in the interface. Alternatively, programmatically add a credential via the API running on `http://localhost:5055`:

```bash
curl -X POST http://localhost:5055/api/credentials \
  -H "Content-Type: application/json" \
  -d '{
        "provider": "openai",
        "api_key": "sk-····",
        "name": "My OpenAI"
      }'

```

## Deploy Open Notebook from Source

Use this approach if you are modifying code, running tests, or contributing to the `lfnovo/open-notebook` project.

### Install Development Dependencies

You need Python 3.11+, Node.js 18+, and the `uv` package manager installed on your workstation.

### Clone and Build

Execute these commands in your terminal:

```bash
git clone https://github.com/lfnovo/open-notebook.git
cd open-notebook
uv sync
npm install --prefix frontend

```

The `uv sync` command installs Python dependencies using [`pyproject.toml`](https://github.com/lfnovo/open-notebook/blob/main/pyproject.toml), while `npm install` resolves the frontend packages.

### Launch the Application Stack

Run the orchestration command:

```bash
make start-all

```

The `Makefile` starts SurrealDB, launches the FastAPI server via `uv run uvicorn api.main:app --reload`, and runs the Next.js development server. In this mode, the API is available at `http://localhost:5055` and the UI at `http://localhost:8502`.

## Verify Deployment and Run Your First Workflow

Once the containers or source processes are running, confirm API connectivity by creating a notebook:

```bash
curl -X POST http://localhost:5055/api/notebooks \
  -H "Content-Type: application/json" \
  -d '{"title":"Research on AI"}'

```

You can also trigger an ingestion workflow programmatically. The following Python script imports `source_graph` from `open_notebook.graphs.source` and processes a document URL:

```python
import asyncio
from open_notebook.graphs.source import source_graph

async def ingest(url: str):
    await source_graph.ainvoke({"url": url})

asyncio.run(ingest("https://arxiv.org/pdf/2302.12345.pdf"))

```

For fully offline AI inference, refer to [`examples/docker-compose-ollama.yml`](https://github.com/lfnovo/open-notebook/blob/main/examples/docker-compose-ollama.yml) in the repository to integrate a local Ollama container.

## Summary

- **Docker Compose** is the recommended way to deploy open-notebook for both local and production use, requiring only a single `docker compose up -d` command after configuring `OPEN_NOTEBOOK_ENCRYPTION_KEY` in the official [`docker-compose.yml`](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml).
- The stack includes a **Next.js frontend** on port `8502`, a **FastAPI backend** on port `5055`, and **SurrealDB** on port `8000`, connected via Docker networking and persistent volumes.
- **Developers** can deploy open-notebook from source using `uv sync`, `npm install --prefix frontend`, and `make start-all`, which executes [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py) with hot-reload enabled.
- Post-deployment, the REST API at `http://localhost:5055` exposes endpoints for credentials, notebooks, and LangGraph workflows.
- Offline deployments are supported by referencing the Ollama example compose file located at [`examples/docker-compose-ollama.yml`](https://github.com/lfnovo/open-notebook/blob/main/examples/docker-compose-ollama.yml).

## Frequently Asked Questions

### Can I deploy Open Notebook without using Docker?

Yes, but you must manage the dependencies manually. Install Python 3.11+, Node.js 18+, `uv`, and SurrealDB separately, then run `make start-all` in the cloned `lfnovo/open-notebook` repository to launch all processes. This path is intended for active development rather than production hosting.

### What should I set for the `OPEN_NOTEBOOK_ENCRYPTION_KEY` variable?

Replace the placeholder `change-me-to-a-secret-string` in [`docker-compose.yml`](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml) with a long, randomly generated string before you deploy open-notebook. This key is consumed by the `open_notebook` container to secure sensitive application data at rest.

### How do I add a local LLM such as Ollama to my deployment?

Mount or link an Ollama container to the Docker network and configure the provider in the Open Notebook UI or through the API credentials endpoint at `http://localhost:5055/api/credentials`. The repository includes [`examples/docker-compose-ollama.yml`](https://github.com/lfnovo/open-notebook/blob/main/examples/docker-compose-ollama.yml), which demonstrates how to add a local model service for fully offline inference.

### Is the single-container deployment still maintained?

The single-container option based on `Dockerfile.single` is deprecated and scheduled for removal in version 2. New installations should use the multi-service [`docker-compose.yml`](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml) found in the root of the repository, as it provides clearer separation of concerns and reliable persistent data handling.