Open Notebook Configuration Guide

Reviewed against v1.14.0 Compose, current environment reference, and source installation on 2026-09-30. Commands below are illustrative deployment examples; no containers or authenticated provider calls were launched for this review.

Docker deployment and persistence

Use the upstream docker-compose.yml, which has services **surrealdb and open_notebook**, rather than substituting an unverified image location. The reviewed application image is lfnovo/open_notebook:v1-latest, and the database image is surrealdb/surrealdb:v2. Record resolved image digests for reproducibility; these tags can change. Do not replace the database with an arbitrary latest major.

curl --fail --location --output docker-compose.yml \
  https://raw.githubusercontent.com/lfnovo/open-notebook/v1.14.0/docker-compose.yml

The downloaded file contains a literal encryption-key placeholder. Replace it in the file, or change that environment entry to OPEN_NOTEBOOK_ENCRYPTION_KEY=${OPEN_NOTEBOOK_ENCRYPTION_KEY:?Set a key} and supply the variable through your deployment's secret mechanism. A shell export alone cannot override a literal Compose environment entry. Add the password to the application environment if authentication is needed; it is not in the default Compose application environment automatically.

docker compose up -d
docker compose logs --tail=100 open_notebook
docker compose stop

Application UI/API ports are 8502/5055. For a local-only installation bind them to 127.0.0.1; use HTTPS and authenticated access when operating remotely. The upstream SurrealDB debug port binds to loopback, while the application reaches it on the Compose network. Use matching database credentials for both services.

Persistent mounts in this file are:

The source uses ./data/uploads, not an UPLOAD_DIR=/app/uploads configuration. Preserving only uploads loses podcast files and chat checkpoints.

Environment variables

The bundled Python client helpers additionally read OPEN_NOTEBOOK_URL (default backend http://localhost:5055) and OPEN_NOTEBOOK_PASSWORD. They do not need database credentials or the encryption key. OPEN_NOTEBOOK_URL is a helper setting, not a replacement for the server's API_URL.

Provider key environment variables such as OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, and GROQ_API_KEY remain legacy fallbacks. Upstream now deprecates that mechanism; configure stored credentials through Manage → Models or the credential API for new automation.

AI provider setup

Use the UI to add a configuration, test it, discover models, and select models for registration. A provider supporting language models does not necessarily support embeddings, transcription, or speech. Inspect /api/models/providers and the chosen model's capabilities. Model/credential tests may invoke paid provider APIs.

The following Python example is illustrative. Run from the skill's scripts/ directory. It reads an existing provider secret from the environment only to submit it to the user's own Open Notebook credential store; it does not print the secret. Choose a language-model name returned by discovery before calling the function. Do not automatically register every discovered name as a language model.

import os
from _common import record_path, request_json


def register_openai_language_model(selected_name):
    credential = request_json("POST", "/credentials", json={
        "name": "Research provider", "provider": "openai",
        "api_key": os.environ["OPENAI_API_KEY"],
        "modalities": ["language"],
    })
    credential_path = "/credentials/" + record_path(credential["id"])
    check = request_json("POST", credential_path + "/test")
    if not check["success"]:
        raise RuntimeError(check["message"])
    discovery = request_json("POST", credential_path + "/discover")
    selected = next(
        model for model in discovery["discovered"] if model["name"] == selected_name
    )
    registered = request_json("POST", credential_path + "/register-models", json={
        "models": [{"name": selected["name"], "provider": selected["provider"],
                    "model_type": "language"}],
    })
    return credential["id"], registered

Discovery returns discovered, not models; those objects have names, not model record IDs. Registration returns counts, not IDs. Retrieve registered records with GET /api/models?type=language and choose the matching name, provider, and credential. Register a suitable embedding model separately. Explicitly assign defaults using PUT /api/models/defaults, for example default_chat_model and default_embedding_model with their registered IDs. /api/models/auto-assign fills only these two required slots and can select a cloud provider; review that selection. Speech and other optional slots need explicit assignment when desired.

Deleting a credential without migrate_to also deletes its linked models; a failed connection test is not a reason to delete an existing credential automatically.

Ollama and local processing

Use upstream's Ollama Compose example for a matching network and volume definition. A provider URL such as http://ollama:11434 works only when that service name exists on the application's network. A model server on the Docker host needs the appropriate host route rather than localhost inside the application container. Register both a language and an embedding model actually installed in the local server.

Local inference avoids provider API charges, but still consumes local compute. Check all stages: content extraction, transcription, embeddings, chat, and speech can use separate remote providers. Confirm these settings before restricted data is ingested or a podcast is generated.

Running from source

Docker is a convenient deployment, not a mandatory application runtime. Follow upstream's source installation and its lockfile for interpreter/dependency versions. Its documented setup uses uv sync, a SurrealDB service, a Next.js frontend, and separate API/worker processes. In the upstream checkout, after configuring .env:

make api

In a separate terminal:

make worker

A working /health endpoint does not prove the worker is running. Without it, background ingestion/embedding/podcast jobs remain pending. The source frontend's development port is 3000, unlike Docker's 8502. No separate Python client SDK is required by this skill; the bundled requests wrappers call the REST API directly.

Backup and restore

Keep a consistent copy of both persistent directories and retain the encryption key separately. For a local deployment using the upstream bind mounts, a cold filesystem backup is an illustrative option: stop both services, archive the data, then restart. Use a fresh backup path; do not overwrite the only prior backup.

docker compose stop
tar -czf open-notebook-backup-YYYYMMDD.tar.gz notebook_data surreal_data
docker compose start

To restore, stop the services, preserve the current directories, restore the archive into the same Compose directory, and use the same encryption key and compatible image/database versions before starting. Test restoration on a separate deployment. A database-only export is insufficient for files and SQLite conversation state.