# Environment Variables for Deploying Open Notebook in Production: Complete Guide

> Deploy Open Notebook in production with essential environment variables. Learn about OPEN_NOTEBOOK_ENCRYPTION_KEY, SURREAL_* database settings, API_URL, and CORS_ORIGINS.

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

---

**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`](https://github.com/lfnovo/open-notebook/blob/main/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.

```bash
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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`:

```dotenv

# 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`](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml) file injects these variables into containers at startup. The FastAPI entry point in [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/database/__init__.py) uses the `SURREAL_*` variables to establish the WebSocket connection.

Example Docker Compose snippet:

```yaml
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`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py)
- Five `SURREAL_*` variables configure the database connection via [`open_notebook/database/__init__.py`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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.