# How to Set Up Open Notebook Locally: Complete Docker Installation Guide

> Easily set up Open Notebook locally with our Docker installation guide. Configure SurrealDB and the Open Notebook container to start private research locally at localhost:8502.

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

---

**Deploy Open Notebook locally using Docker Compose by configuring the SurrealDB service and Open Notebook container with a custom encryption key, then accessing the UI at `localhost:8502` to begin private research.**

Open Notebook is a privacy-first research assistant built by `lfnovo/open-notebook` that combines a Next.js frontend, FastAPI backend, and SurrealDB database. To set up Open Notebook locally, you only need Docker Desktop and the provided [[`docker-compose.yml`](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml)](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml) configuration, which orchestrates all three tiers of the application architecture.

## Architecture Overview

Open Notebook follows a modular three-tier design. The **Frontend** tier runs a Next.js 16/React 19 interface that communicates with the backend over HTTP. The **API** tier consists of a FastAPI server that orchestrates LangGraph workflows and manages AI provider selection via the Esperanto library. The **Database** tier uses SurrealDB to store notebooks, sources, notes, embeddings, and graph relationships.

## Prerequisites

- Docker Desktop installed and running (Docker Engine 20.10.0+ recommended)
- 4GB of available RAM for the container stack
- (Optional) Git for cloning the repository

## Step-by-Step Local Setup

### Download the Docker Compose Configuration

Create a project directory and save the official [`docker-compose.yml`](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml) file. The configuration defines two services: `surrealdb` for persistent data storage and `open_notebook` for the application server and UI.

```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=my-secret-key
      - 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]

```

### Configure Encryption Keys and Environment Variables

Before starting the services, you must set the `OPEN_NOTEBOOK_ENCRYPTION_KEY` environment variable in the compose file. This key encrypts sensitive data in the database. Refer to [`.env.example`](https://github.com/lfnovo/open-notebook/blob/main/.env.example) for the complete list of configurable variables, including database credentials and API endpoints.

### Launch the Container Stack

Execute the following command in your project directory to start the stack in detached mode:

```bash
docker compose up -d

```

This command initializes the SurrealDB instance and the Open Notebook service. The [[`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py)](https://github.com/lfnovo/open-notebook/blob/main/api/main.py) entry point registers all routers and enables CORS for the FastAPI application.

### Access the Web Interface

Once containers are healthy (approximately 15 seconds), navigate to `http://localhost:8502` to access the Streamlit-based user interface. The API documentation is available at `http://localhost:5055/docs`.

### Configure AI Model Providers

In the UI, navigate to **Models → + Add Configuration** to add your AI provider credentials. The system supports OpenAI, Anthropic, and local models through the [[`open_notebook/ai/model_manager.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/ai/model_manager.py)](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/ai/model_manager.py) abstraction layer.

## Alternative Setup for Local LLMs

For completely offline operation without external API calls, use the Ollama configuration file located at [[`examples/docker-compose-ollama.yml`](https://github.com/lfnovo/open-notebook/blob/main/examples/docker-compose-ollama.yml)](https://github.com/lfnovo/open-notebook/blob/main/examples/docker-compose-ollama.yml). This setup includes an Ollama service alongside the standard stack, allowing you to use local LLMs like Llama 2 or Mistral for text generation and embeddings.

## Programmatic API Configuration

You can configure models and manage notebooks programmatically via the REST API. The FastAPI server exposes endpoints for source ingestion, note creation, and chat workflows defined in [`open_notebook/graphs/`](https://github.com/lfnovo/open-notebook/tree/main/open_notebook/graphs).

**Add a model using cURL:**

```bash
curl -X POST http://localhost:5055/models \
  -H "Content-Type: application/json" \
  -d '{
        "provider": "openai",
        "api_key": "sk-…",
        "model_name": "gpt-4o-mini",
        "max_context": 8192
      }'

```

**Add a model using Python:**

```python
import httpx

client = httpx.AsyncClient(base_url="http://localhost:5055")
await client.post("/models", json={
    "provider": "anthropic",
    "api_key": "my-anthropic-key",
    "model_name": "claude-3-5-sonnet",
    "max_context": 100_000,
})

```

## Summary

- Open Notebook requires Docker Desktop to run the three-tier architecture locally
- The [`docker-compose.yml`](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml) file configures SurrealDB and the Open Notebook service with proper networking and volumes
- You must set `OPEN_NOTEBOOK_ENCRYPTION_KEY` before starting the containers for data security
- Access the UI at `localhost:8502` and the API at `localhost:5055` after launching the stack
- Support for local AI models is available via the Ollama compose configuration

## Frequently Asked Questions

### What ports need to be open for local Open Notebook?

Open Notebook requires ports `8502` for the web interface and `5055` for the FastAPI backend. If you are accessing SurrealDB directly from external tools, port `8000` must also be available. These are configured in the [[`docker-compose.yml`](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml)](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml) service definitions.

### Can I use a local LLM instead of OpenAI or Anthropic?

Yes, you can run completely local AI models using the [[`examples/docker-compose-ollama.yml`](https://github.com/lfnovo/open-notebook/blob/main/examples/docker-compose-ollama.yml)](https://github.com/lfnovo/open-notebook/blob/main/examples/docker-compose-ollama.yml) configuration. This includes an Ollama container that provides local LLM capabilities for text generation and embeddings without sending data to external APIs.

### Where is data stored when running Open Notebook locally?

Data persists in two Docker volumes mapped to your host filesystem: `./surreal_data` for the SurrealDB database files and `./notebook_data` for application data. The SurrealDB container uses RocksDB as the underlying storage engine via the command defined in the compose file.

### How do I reset the database in my local setup?

To reset the database, stop the containers with `docker compose down`, then delete the `./surreal_data` and `./notebook_data` directories from your project folder. When you restart the stack with `docker compose up -d`, the system will initialize fresh database instances.