Open Notebook Environment Variables Required for Production Deployment

Six environment variables must be defined for production: OPEN_NOTEBOOK_ENCRYPTION_KEY, SURREAL_URL, SURREAL_USER, SURREAL_PASSWORD, SURREAL_NAMESPACE, and SURREAL_DATABASE. Missing any of these causes the service defined in api/main.py to fail during startup or lose connectivity to SurrealDB.

When deploying the lfnovo/open-notebook repository to production, you must configure specific environment variables to handle credential encryption, database authentication, and security policies. The application reads these values at startup to initialize the FastAPI backend and establish encrypted connections to SurrealDB. This guide details the mandatory variables, their roles in the system, and the configuration files that govern production behavior.

Required Environment Variables

Six variables are marked as required in docs/5-CONFIGURATION/environment-reference.md and have no safe defaults for production use. The application will terminate immediately if any are undefined.

OPEN_NOTEBOOK_ENCRYPTION_KEY

The OPEN_NOTEBOOK_ENCRYPTION_KEY variable is mandatory for production deployments. This key encrypts AI-provider credentials stored in SurrealDB; without it, the credential system cannot initialize and the API will refuse to start. Generate a strong, random secret and store it securely in your production secrets management system.

SurrealDB Connection Credentials

Five variables configure the WebSocket connection to SurrealDB. These are consumed during application initialization in api/main.py:

• SURREAL_URL: The WebSocket endpoint (e.g., ws://surrealdb:8000/rpc)
• SURREAL_USER: Database user with write access (override the default root)
• SURREAL_PASSWORD: Password for the database user (override the default root)
• SURREAL_NAMESPACE: Logical namespace inside SurrealDB (default open_notebook)
• SURREAL_DATABASE: Target database name (default open_notebook)

Optional Production Variables

While the following variables are not required for the service to start, configuring them is strongly recommended for security and proper proxy handling.

UI Password Protection

Set OPEN_NOTEBOOK_PASSWORD to enforce password authentication on the web interface. This is essential for any public-facing deployment to prevent unauthorized access to notebooks and AI configurations.

Reverse Proxy and CORS Configuration

When running behind a reverse proxy or load balancer:

• API_URL: Set to the public URL (e.g., https://notebook.example.com) so the frontend can reach the backend correctly
• CORS_ORIGINS: Whitelist the exact origin(s) that will call the API (e.g., https://notebook.example.com). Leaving this as the default * is insecure for production and exposes your API to cross-origin attacks

Corporate Proxy Settings

If outbound traffic must route through a corporate proxy, define HTTP_PROXY, HTTPS_PROXY, and NO_PROXY as needed for your network topology.

Minimal Production Configuration

Create a .env.production file based on the template in .env.example with the following required minimum:

# Security - always set

OPEN_NOTEBOOK_ENCRYPTION_KEY=your-strong-secret-key

# Database - required

SURREAL_URL=ws://surrealdb:8000/rpc
SURREAL_USER=production_user
SURREAL_PASSWORD=secure_password
SURREAL_NAMESPACE=open_notebook
SURREAL_DATABASE=open_notebook

# Optional but recommended for public deployments

OPEN_NOTEBOOK_PASSWORD=your-ui-password
API_URL=https://notebook.example.com
CORS_ORIGINS=https://notebook.example.com

Docker Compose Production Deployment

The repository's docker-compose.yml demonstrates the proper injection of these variables. Reference this structure for containerized deployments:

services:
  api:
    image: lfnovo/open-notebook:latest
    env_file:
      - .env.production
    ports:
      - "5055:5055"
    depends_on:
      - surrealdb
  surrealdb:
    image: surrealdb/surrealdb:latest
    environment:
      - SURREAL_USER=production_user
      - SURREAL_PASSWORD=secure_password
    ports:
      - "8000:8000"

Key Configuration Files

Understanding where these variables are defined helps troubleshoot deployment failures:

• docs/5-CONFIGURATION/environment-reference.md: Complete list of variables with defaults and descriptions
• .env.example: Template showing all supported variables; copy and edit for your production environment
• CONFIGURATION.md: High-level guidance on deploying Open Notebook, including production security considerations
• docker-compose.yml: Example orchestration file demonstrating environment variable injection for containerized stacks
• api/main.py: FastAPI entry point that reads environment variables and initializes the application context

Deprecated Variables to Remove

AI-provider credentials (such as OPENAI_API_KEY or ANTHROPIC_API_KEY) are now managed through the Settings → API Keys UI and encrypted in SurrealDB using your OPEN_NOTEBOOK_ENCRYPTION_KEY. These legacy environment variables are deprecated and should be removed from production configurations to prevent confusion and potential security leaks.

Summary

• OPEN_NOTEBOOK_ENCRYPTION_KEY is mandatory for encrypting AI credentials stored in SurrealDB
• Five SurrealDB variables (SURREAL_URL, SURREAL_USER, SURREAL_PASSWORD, SURREAL_NAMESPACE, SURREAL_DATABASE) are required for database connectivity
• OPEN_NOTEBOOK_PASSWORD, API_URL, and CORS_ORIGINS are optional but essential for securing public-facing deployments
• Legacy AI provider environment variables are deprecated; configure providers via the UI instead
• Reference docs/5-CONFIGURATION/environment-reference.md and .env.example for the complete variable schema

Frequently Asked Questions

What happens if I don't set OPEN_NOTEBOOK_ENCRYPTION_KEY in production?

The service will fail to start because it cannot initialize the encryption system required to secure AI provider credentials. This variable has no default value and must be explicitly defined.

Can I use the default SurrealDB credentials in production?

No. While SURREAL_USER defaults to root and SURREAL_PASSWORD defaults to root, you must override these with secure, production-specific credentials. The defaults are only suitable for local development environments.

How do I configure Open Notebook behind a reverse proxy?

Set the API_URL environment variable to your public domain (e.g., https://notebook.example.com) and configure CORS_ORIGINS to whitelist your exact domain instead of using the default * wildcard. This ensures the frontend correctly communicates with the backend through the proxy layer.

Are OpenAI API keys still set via environment variables?

No. According to the source code and CONFIGURATION.md, AI provider credentials are now stored via the Settings → API Keys UI and encrypted in SurrealDB. Environment variables like OPENAI_API_KEY are deprecated and should be removed from your production environment files.

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