Environment Variables for Deploying Open Notebook in Production: Complete Guide

To deploy Open Notebook in production, you must configure OPEN_NOTEBOOK_ENCRYPTION_KEY for credential encryption, five SURREAL_* variables for database connectivity, and API_URL with CORS_ORIGINS for frontend routing.

Open Notebook is an open-source note-taking platform built with a Next.js frontend, FastAPI backend, and SurrealDB database. Configuring the correct environment variables for deploying Open Notebook in production ensures secure credential storage, proper database connectivity, and correct routing behind reverse proxies. This guide covers the mandatory variables extracted from the source code in lfnovo/open-notebook.

Required Core Security Variables

OPEN_NOTEBOOK_ENCRYPTION_KEY

The OPEN_NOTEBOOK_ENCRYPTION_KEY variable is mandatory for the credential system. According to api/main.py, this key encrypts AI-provider API keys stored in SurrealDB. Without it, the Settings UI cannot save or retrieve credentials, and the application will abort at startup with a clear error message.

OPEN_NOTEBOOK_ENCRYPTION_KEY=your-super-secret-random-string

Required Database Connection Variables

The FastAPI backend communicates with SurrealDB via WebSocket. You must provide five variables read by open_notebook/database/__init__.py:

• SURREAL_URL: WebSocket endpoint (e.g., ws://surrealdb:8000/rpc)
• SURREAL_USER: Database user with read/write permissions
• SURREAL_PASSWORD: Strong password for the database user
• SURREAL_NAMESPACE: Logical namespace (typically open_notebook)
• SURREAL_DATABASE: Specific database name (typically open_notebook)

Missing any of these causes the database client initialization to fail.

Required Frontend-to-Backend Routing Variables

When running behind a reverse proxy or custom domain, configure how the Next.js frontend reaches the FastAPI API.

API_URL and CORS_ORIGINS

• API_URL: The public base URL the frontend uses to call FastAPI (e.g., https://notebook.example.com)
• CORS_ORIGINS: Comma-separated whitelist of origins allowed to call the API. In production, the default wildcard (*) is unsafe; set this to your frontend's exact origin.

These are validated at startup in api/main.py to ensure proper CORS handling.

Optional Production Variables

While not required for basic functionality, these variables improve security and stability:

• OPEN_NOTEBOOK_PASSWORD: Enables basic password protection for the entire UI
• API_CLIENT_TIMEOUT: Frontend timeout for API calls (default 600s for long-running jobs)
• ESPERANTO_LLM_TIMEOUT: LLM inference timeout in seconds (e.g., 120)
• TTS_BATCH_SIZE: Concurrent text-to-speech requests (e.g., 5)
• ESPERANTO_TTS_TIMEOUT: TTS operation timeout (e.g., 600)
• HTTP_PROXY, HTTPS_PROXY, NO_PROXY: Required only behind corporate proxies

Minimal Production Configuration Example

Create a .env file based on the template in .env.example:

# Core security

OPEN_NOTEBOOK_ENCRYPTION_KEY=super-secret-key-12345

# SurrealDB connection

SURREAL_URL=ws://surrealdb:8000/rpc
SURREAL_USER=prod_user
SURREAL_PASSWORD=ProdStrongPass!
SURREAL_NAMESPACE=open_notebook
SURREAL_DATABASE=open_notebook

# Frontend-API routing

API_URL=https://notebook.example.com
CORS_ORIGINS=https://notebook.example.com

# Optional UI protection

OPEN_NOTEBOOK_PASSWORD=UiStrongPass!

# Timeouts for long-running jobs

API_CLIENT_TIMEOUT=600
ESPERANTO_LLM_TIMEOUT=120

How Variables Are Loaded at Runtime

The docker-compose.yml file injects these variables into containers at startup. The FastAPI entry point in api/main.py validates that required variables are present, aborting with a clear error if OPEN_NOTEBOOK_ENCRYPTION_KEY or database credentials are missing. The SurrealDB client in open_notebook/database/__init__.py uses the SURREAL_* variables to establish the WebSocket connection.

Example Docker Compose snippet:

services:
  api:
    environment:
      - OPEN_NOTEBOOK_ENCRYPTION_KEY=${OPEN_NOTEBOOK_ENCRYPTION_KEY}
      - SURREAL_URL=${SURREAL_URL}
      - SURREAL_USER=${SURREAL_USER}
      - SURREAL_PASSWORD=${SURREAL_PASSWORD}
      - SURREAL_NAMESPACE=${SURREAL_NAMESPACE}
      - SURREAL_DATABASE=${SURREAL_DATABASE}
      - API_URL=${API_URL}
      - CORS_ORIGINS=${CORS_ORIGINS}

Summary

• OPEN_NOTEBOOK_ENCRYPTION_KEY is mandatory for credential encryption and validated by api/main.py
• Five SURREAL_* variables configure the database connection via open_notebook/database/__init__.py
• API_URL and CORS_ORIGINS secure frontend-to-backend communication behind reverse proxies
• Reference docs/5-CONFIGURATION/environment-reference.md for the complete variable list
• Use .env.example as a template for new deployments

Frequently Asked Questions

What happens if I don't set OPEN_NOTEBOOK_ENCRYPTION_KEY?

The application will abort at startup with a clear error message. This key is required by the credential system in api/main.py to encrypt AI provider keys stored in SurrealDB. Without it, the Settings UI cannot save or read credentials.

Can I use a remote SurrealDB instance instead of Docker?

Yes. Set SURREAL_URL to the remote WebSocket endpoint (e.g., wss://db.example.com:8000/rpc) and provide the appropriate SURREAL_USER, SURREAL_PASSWORD, SURREAL_NAMESPACE, and SURREAL_DATABASE values for your external database.

Why is CORS_ORIGINS required in production?

The default wildcard (*) is unsafe for public-facing deployments. CORS_ORIGINS restricts which domains can call the FastAPI backend, preventing cross-site request forgery when the Next.js frontend runs on a different origin than the API.

Where can I find the complete list of environment variables?

The authoritative reference is docs/5-CONFIGURATION/environment-reference.md in the repository. This file documents all variables, their defaults, and descriptions, while .env.example provides a minimal working template.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}