# Open Notebook

# Overview

Open Notebook is a self-hosted AI research notebook application — a local alternative
to Google NotebookLM. It allows structured AI-assisted research sessions where
sources (documents, URLs, text) are ingested into a notebook and queried via an LLM
for synthesis, summaries, and question-answering.

It uses SurrealDB as its backend database for storing notebooks, sources, and
conversation state.

## Access

| Type      | URL                                       | Notes                                           |
|-----------|-------------------------------------------|-------------------------------------------------|
| Internal  | `https://notebook.home.local`             | LAN access via Step-CA TLS                      |
| External  | `https://notebook.jeeves5454.ddns.net`    | Authentik SSO + GeoBlock + CrowdSec             |

## Containers in This Stack

| Container          | Image                            | Role                        |
|--------------------|----------------------------------|-----------------------------|
| `open-notebook`    | `lfnovo/open_notebook:v1-latest` | Application server (Streamlit) |
| `open-notebook-db` | `surrealdb/surrealdb:v2`         | SurrealDB database backend  |

## Configuration

**Compose project:** `ai-stack`

### Environment Variables

| Variable               | Value / Notes                                              |
|------------------------|------------------------------------------------------------|
| `API_URL`              | `https://notebook.home.local`                              |
| `CORS_ORIGINS`         | `https://notebook.home.local,https://notebook.jeeves5454.ddns.net` |
| `INTERNAL_API_URL`     | `http://localhost:5055`                                    |
| `SURREAL_URL`          | `ws://open-notebook-db:8000/rpc`                           |
| `SURREAL_NAMESPACE`    | `open_notebook`                                            |
| `SURREAL_DATABASE`     | `open_notebook`                                            |
| `SURREAL_USER`         | `root`                                                     |
| `SURREAL_PASSWORD`     | **REDACTED**                                               |
| `HOSTNAME`             | `0.0.0.0`                                                  |

### Traefik Labels

```yaml
# External route
traefik.http.routers.open-notebook-ext.rule: Host(`notebook.jeeves5454.ddns.net`)
traefik.http.routers.open-notebook-ext.entrypoints: websecure
traefik.http.routers.open-notebook-ext.tls.certresolver: letsencrypt
traefik.http.routers.open-notebook-ext.middlewares: authentik-auth@docker,plex-geoblock@file,crowdsec-bouncer@file
traefik.http.routers.open-notebook-ext.service: open-notebook-ui-svc
traefik.http.routers.open-notebook-ext.priority: 1

# Internal route
traefik.http.routers.open-notebook-int.rule: Host(`notebook.home.local`)
traefik.http.routers.open-notebook-int.entrypoints: websecure
traefik.http.routers.open-notebook-int.tls.certresolver: step-ca
traefik.http.routers.open-notebook-int.service: open-notebook-ui-svc
traefik.http.routers.open-notebook-int.priority: 1

traefik.http.services.open-notebook-ui-svc.loadbalancer.server.port: 8502
```

## Volumes / Bind Mounts

| Host Path                                                      | Container Path | Purpose                     |
|----------------------------------------------------------------|----------------|-----------------------------|
| `/media/jeeves/1TB_Vol1/docker/open-notebook/notebook_data`    | `/app/data`    | Notebook content and uploads (Ceph OSD) |
| `/home/jeeves/docker/open-notebook/surreal_data`               | `/mydata`      | SurrealDB data files        |

Notebook data (uploaded sources, generated content) is stored on the Ceph OSD
volume (`1TB_Vol1`) to keep large research files off the system NVMe.

### Sub-section: SurrealDB

`open-notebook-db` runs SurrealDB v2, a multi-model database used by Open Notebook
to store all notebook definitions, source metadata, embeddings, and conversation
history.

SurrealDB is connected to `open-notebook` via WebSocket at
`ws://open-notebook-db:8000/rpc` over the `ai-internal` network. It is not
exposed to `traefik-net` — no external access.

## Networks

| Network                 | Purpose                                         |
|-------------------------|-------------------------------------------------|
| `ai-stack_ai-internal`  | `open-notebook` ↔ `open-notebook-db` communication |
| `traefik-net`           | Exposes the Open Notebook UI via Traefik        |

`open-notebook-db` is on `ai-internal` only and never on `traefik-net`.

## Dependencies

- `open-notebook-db` (SurrealDB must be running before the app starts)
- Ollama or an external LLM API configured within the app settings
- Authentik for SSO on the external route
- Ceph OSD volume mounted at `/media/jeeves/1TB_Vol1`

## Notes / Gotchas

- The `v1-latest` image tag tracks the latest v1 stable release. Breaking changes
  between major versions may require a database migration.
- SurrealDB stores its data in the bind-mounted `surreal_data` directory. This must
  be backed up before upgrades to SurrealDB v3+ as schema changes are not
  automatically reversible.
- LLM provider settings (which Ollama model to use, API keys for external providers)
  are configured inside the Open Notebook UI, not via environment variables.
- `CORS_ORIGINS` must include both the internal and external URLs — missing one will
  cause browser CORS errors for the corresponding route.

---
*Last Updated: 2026-06-16*