# Open Notebook Environment Variables Required for Production Deployment

> Secure your Open Notebook production deployment by defining six essential environment variables. Learn what they are and why they're critical for startup and SurrealDB connectivity.

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

---

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

```bash

# 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`](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml) demonstrates the proper injection of these variables. Reference this structure for containerized deployments:

```yaml
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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/CONFIGURATION.md)**: High-level guidance on deploying Open Notebook, including production security considerations
- **[`docker-compose.yml`](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml)**: Example orchestration file demonstrating environment variable injection for containerized stacks
- **[`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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.