vrr/open-notebook

Fork 0

mirror of https://github.com/lfnovo/open-notebook.git synced 2026-04-28 03:19:59 +00:00

Luis Novo ec41ef8f2f

Development Build / extract-version (push) Has been cancelled

Details

Tests / Backend Tests (push) Has been cancelled

Details

Tests / Frontend Tests (push) Has been cancelled

Details

Development Build / build-regular (push) Has been cancelled

Details

Development Build / build-single (push) Has been cancelled

Details

Development Build / summary (push) Has been cancelled

Details

feat(api): add configurable CORS origins via CORS_ORIGINS (#767 )

Replace hardcoded `allow_origins=["*"]` with a parsed `CORS_ORIGINS`
environment variable (comma-separated). Default remains `*` for
backward compatibility — no existing deployment breaks — but the API
now logs a startup warning prompting users to set it explicitly for
production.

Exception handlers now route their CORS headers through a shared
`_cors_headers()` helper that mirrors Starlette's CORSMiddleware
behavior: reflects the request Origin when allowed (handling the
browser-rejected `*` + credentials combination correctly), and omits
`Access-Control-Allow-Origin` for disallowed origins so error bodies
don't leak cross-origin when `CORS_ORIGINS` is configured.

Closes #585, #730.

Based on the original work by Greg Grace in #597; rewritten on top of
current main to address prior review feedback (load_dotenv kept at
top, `import os` grouped with stdlib, `_cors_headers` defined before
its exception-handler callers, origins parsed once at module load)
and to choose a non-breaking default paired with a startup warning
instead of a stricter-by-default origin.

Co-authored-by: Greg Grace <ggrace@519lab.com>

2026-04-19 16:22:10 -03:00

12 KiB

Raw Blame History

Complete Environment Reference

Comprehensive list of all environment variables available in Open Notebook.

API Configuration

Variable	Required?	Default	Description
`API_URL`	No	Auto-detected	URL where frontend reaches API (e.g., http://localhost:5055)
`INTERNAL_API_URL`	No	http://localhost:5055	Internal API URL for Next.js server-side proxying
`API_CLIENT_TIMEOUT`	No	300	Client timeout in seconds (how long to wait for API response)
`OPEN_NOTEBOOK_PASSWORD`	No	None	Password to protect Open Notebook instance
`OPEN_NOTEBOOK_ENCRYPTION_KEY`	Yes	None	Secret string to encrypt credentials stored in database (any string works). Required for the credential system. Supports Docker secrets via `_FILE` suffix.
`HOSTNAME`	No	`0.0.0.0` (in Docker)	Network interface for Next.js to bind to. Default `0.0.0.0` ensures accessibility from reverse proxies

Important: OPEN_NOTEBOOK_ENCRYPTION_KEY is required for storing AI provider credentials via the Settings UI. Without it, you cannot save credentials. If you change or lose this key, all stored credentials become unreadable.

Database: SurrealDB

Variable	Required?	Default	Description
`SURREAL_URL`	Yes	ws://surrealdb:8000/rpc	SurrealDB WebSocket connection URL
`SURREAL_USER`	Yes	root	SurrealDB username
`SURREAL_PASSWORD`	Yes	root	SurrealDB password
`SURREAL_NAMESPACE`	Yes	open_notebook	SurrealDB namespace
`SURREAL_DATABASE`	Yes	open_notebook	SurrealDB database name

Database: Retry Configuration

Variable	Required?	Default	Description
`SURREAL_COMMANDS_RETRY_ENABLED`	No	true	Enable retries on failure
`SURREAL_COMMANDS_RETRY_MAX_ATTEMPTS`	No	3	Maximum retry attempts
`SURREAL_COMMANDS_RETRY_WAIT_STRATEGY`	No	exponential_jitter	Retry wait strategy (exponential_jitter/exponential/fixed/random)
`SURREAL_COMMANDS_RETRY_WAIT_MIN`	No	1	Minimum wait time between retries (seconds)
`SURREAL_COMMANDS_RETRY_WAIT_MAX`	No	30	Maximum wait time between retries (seconds)

Database: Concurrency

Variable	Required?	Default	Description
`SURREAL_COMMANDS_MAX_TASKS`	No	5	Maximum concurrent database tasks

LLM Timeouts

Variable	Required?	Default	Description
`ESPERANTO_LLM_TIMEOUT`	No	60	LLM inference timeout in seconds
`ESPERANTO_SSL_VERIFY`	No	true	Verify SSL certificates (false = development only)
`ESPERANTO_SSL_CA_BUNDLE`	No	None	Path to custom CA certificate bundle

Embeddings

Variable	Required?	Default	Description
`OPEN_NOTEBOOK_EMBEDDING_BATCH_SIZE`	No	50	Number of texts sent per embedding batch. Lower this for CPU-only or stricter OpenAI-compatible embedding providers.

API / CORS

Variable	Required?	Default	Description
`CORS_ORIGINS`	No	`*`	Comma-separated list of origins allowed to call the API (e.g. `https://app.example.com,https://www.example.com`). Default `` accepts any origin; for production, set this explicitly to your frontend origin(s)*. Changes require an API restart. The API logs a warning on startup when unset.

When to change this:

You access the UI at a custom domain (reverse proxy, HTTPS, public deployment).
The frontend runs on a different port than 3000.
You serve the frontend from a different host than the API (e.g. CDN).

Example for a production deployment behind a reverse proxy:

CORS_ORIGINS=https://notebook.example.com

Text-to-Speech (TTS)

Variable	Required?	Default	Description
`TTS_BATCH_SIZE`	No	5	Concurrent TTS requests (1-5, depends on provider)

Content Extraction

Variable	Required?	Default	Description
`FIRECRAWL_API_KEY`	No	None	Firecrawl API key for advanced web scraping
`JINA_API_KEY`	No	None	Jina AI API key for web extraction

Setup:

Firecrawl: https://firecrawl.dev/
Jina: https://jina.ai/

Network / Proxy

Variable	Required?	Default	Description
`HTTP_PROXY`	No	None	HTTP proxy URL for outbound HTTP requests
`HTTPS_PROXY`	No	None	HTTPS proxy URL for outbound HTTPS requests
`NO_PROXY`	No	None	Comma-separated list of hosts to bypass proxy

Route all outbound HTTP requests through a proxy server. Useful for corporate/firewalled environments.

The underlying libraries (esperanto, content-core, podcast-creator) automatically detect proxy settings from these standard environment variables.

Affects:

AI provider API calls (OpenAI, Anthropic, Google, Groq, etc.)
Content extraction from URLs (web scraping, YouTube transcripts)
Podcast generation (LLM and TTS provider calls)

Format: http://[user:pass@]host:port or https://[user:pass@]host:port

Examples:

# Basic proxy
HTTP_PROXY=http://proxy.corp.com:8080
HTTPS_PROXY=http://proxy.corp.com:8080

# Authenticated proxy
HTTP_PROXY=http://user:password@proxy.corp.com:8080
HTTPS_PROXY=http://user:password@proxy.corp.com:8080

# Bypass proxy for local hosts
NO_PROXY=localhost,127.0.0.1,.local

Debugging & Monitoring

Variable	Required?	Default	Description
`LANGCHAIN_TRACING_V2`	No	false	Enable LangSmith tracing
`LANGCHAIN_ENDPOINT`	No	https://api.smith.langchain.com	LangSmith endpoint
`LANGCHAIN_API_KEY`	No	None	LangSmith API key
`LANGCHAIN_PROJECT`	No	Open Notebook	LangSmith project name

Setup: https://smith.langchain.com/

Environment Variables by Use Case

Minimal Setup (New Installation)

OPEN_NOTEBOOK_ENCRYPTION_KEY=my-secret-key
SURREAL_URL=ws://surrealdb:8000/rpc
SURREAL_USER=root
SURREAL_PASSWORD=password
SURREAL_NAMESPACE=open_notebook
SURREAL_DATABASE=open_notebook

Then configure AI providers via Settings → API Keys in the browser.

Production Deployment

OPEN_NOTEBOOK_ENCRYPTION_KEY=your-strong-secret-key
OPEN_NOTEBOOK_PASSWORD=your-secure-password
API_URL=https://mynotebook.example.com
SURREAL_USER=production_user
SURREAL_PASSWORD=secure_password

Self-Hosted Behind Reverse Proxy

OPEN_NOTEBOOK_ENCRYPTION_KEY=your-secret-key
API_URL=https://mynotebook.example.com

Corporate Environment (Behind Proxy)

OPEN_NOTEBOOK_ENCRYPTION_KEY=your-secret-key
HTTP_PROXY=http://proxy.corp.com:8080
HTTPS_PROXY=http://proxy.corp.com:8080
NO_PROXY=localhost,127.0.0.1

High-Performance Deployment

OPEN_NOTEBOOK_ENCRYPTION_KEY=your-secret-key
SURREAL_COMMANDS_MAX_TASKS=10
TTS_BATCH_SIZE=5
API_CLIENT_TIMEOUT=600

Debugging

OPEN_NOTEBOOK_ENCRYPTION_KEY=your-secret-key
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your-key

Validation

Check if a variable is set:

# Check single variable
echo $OPEN_NOTEBOOK_ENCRYPTION_KEY

# Check multiple
env | grep -E "OPEN_NOTEBOOK|API_URL"

# Print all config
env | grep -E "^[A-Z_]+=" | sort

Notes

Case-sensitive: OPEN_NOTEBOOK_ENCRYPTION_KEY ≠ open_notebook_encryption_key
No spaces: OPEN_NOTEBOOK_ENCRYPTION_KEY=my-key not OPEN_NOTEBOOK_ENCRYPTION_KEY = my-key
Quote values: Use quotes for values with spaces: API_URL="http://my server:5055"
Restart required: Changes take effect after restarting services
Secrets: Don't commit encryption keys or passwords to git
AI Providers: Configure via Settings → API Keys in the browser (not via env vars)
Migration: Use Settings UI to migrate existing env vars to the credential system. See API Configuration

Quick Setup Checklist

Set OPEN_NOTEBOOK_ENCRYPTION_KEY in docker-compose.yml
Set database credentials (SURREAL_*)
Start services
Open browser → Go to Settings → API Keys
Add Credential for your AI provider
Test Connection to verify
Discover & Register Models
Set API_URL if behind reverse proxy
Change SURREAL_PASSWORD in production
Try a test chat

Done!

Legacy: AI Provider Environment Variables (Deprecated)

Deprecated: The following AI provider API key environment variables are deprecated. Configure providers via the Settings UI instead. These variables may still work as a fallback but are no longer recommended.

If you have these variables configured from a previous installation, click the Migrate to Database button in Settings → API Keys to import them into the credential system, then remove them from your configuration.

Variable	Provider	Replacement
`OPENAI_API_KEY`	OpenAI	Settings → API Keys → Add OpenAI Credential
`ANTHROPIC_API_KEY`	Anthropic	Settings → API Keys → Add Anthropic Credential
`GOOGLE_API_KEY`	Google Gemini	Settings → API Keys → Add Google Credential
`GEMINI_API_BASE_URL`	Google Gemini	Configure in Google Gemini credential
`VERTEX_PROJECT`	Vertex AI	Settings → API Keys → Add Vertex AI Credential
`VERTEX_LOCATION`	Vertex AI	Configure in Vertex AI credential
`GOOGLE_APPLICATION_CREDENTIALS`	Vertex AI	Configure in Vertex AI credential
`GROQ_API_KEY`	Groq	Settings → API Keys → Add Groq Credential
`MISTRAL_API_KEY`	Mistral	Settings → API Keys → Add Mistral Credential
`DEEPSEEK_API_KEY`	DeepSeek	Settings → API Keys → Add DeepSeek Credential
`XAI_API_KEY`	xAI	Settings → API Keys → Add xAI Credential
`OLLAMA_API_BASE`	Ollama	Settings → API Keys → Add Ollama Credential
`OPENROUTER_API_KEY`	OpenRouter	Settings → API Keys → Add OpenRouter Credential
`OPENROUTER_BASE_URL`	OpenRouter	Configure in OpenRouter credential
`VOYAGE_API_KEY`	Voyage AI	Settings → API Keys → Add Voyage AI Credential
`ELEVENLABS_API_KEY`	ElevenLabs	Settings → API Keys → Add ElevenLabs Credential
`OPENAI_COMPATIBLE_BASE_URL`	OpenAI-Compatible	Settings → API Keys → Add OpenAI-Compatible Credential
`OPENAI_COMPATIBLE_API_KEY`	OpenAI-Compatible	Configure in OpenAI-Compatible credential
`OPENAI_COMPATIBLE_BASE_URL_LLM`	OpenAI-Compatible	Configure per-service URL in credential
`OPENAI_COMPATIBLE_API_KEY_LLM`	OpenAI-Compatible	Configure per-service key in credential
`OPENAI_COMPATIBLE_BASE_URL_EMBEDDING`	OpenAI-Compatible	Configure per-service URL in credential
`OPENAI_COMPATIBLE_API_KEY_EMBEDDING`	OpenAI-Compatible	Configure per-service key in credential
`OPENAI_COMPATIBLE_BASE_URL_STT`	OpenAI-Compatible	Configure per-service URL in credential
`OPENAI_COMPATIBLE_API_KEY_STT`	OpenAI-Compatible	Configure per-service key in credential
`OPENAI_COMPATIBLE_BASE_URL_TTS`	OpenAI-Compatible	Configure per-service URL in credential
`OPENAI_COMPATIBLE_API_KEY_TTS`	OpenAI-Compatible	Configure per-service key in credential
`DASHSCOPE_API_KEY`	DashScope (Qwen)	Settings → API Keys → Add DashScope Credential
`MINIMAX_API_KEY`	MiniMax	Settings → API Keys → Add MiniMax Credential
`AZURE_OPENAI_API_KEY`	Azure OpenAI	Settings → API Keys → Add Azure OpenAI Credential
`AZURE_OPENAI_ENDPOINT`	Azure OpenAI	Configure in Azure OpenAI credential
`AZURE_OPENAI_API_VERSION`	Azure OpenAI	Configure in Azure OpenAI credential
`AZURE_OPENAI_API_KEY_LLM`	Azure OpenAI	Configure per-service in credential
`AZURE_OPENAI_ENDPOINT_LLM`	Azure OpenAI	Configure per-service in credential
`AZURE_OPENAI_API_VERSION_LLM`	Azure OpenAI	Configure per-service in credential
`AZURE_OPENAI_API_KEY_EMBEDDING`	Azure OpenAI	Configure per-service in credential
`AZURE_OPENAI_ENDPOINT_EMBEDDING`	Azure OpenAI	Configure per-service in credential
`AZURE_OPENAI_API_VERSION_EMBEDDING`	Azure OpenAI	Configure per-service in credential

12 KiB Raw Blame History

Complete Environment Reference

API Configuration

Database: SurrealDB

Database: Retry Configuration

Database: Concurrency

LLM Timeouts

Embeddings

API / CORS

Text-to-Speech (TTS)

Content Extraction

Network / Proxy

Debugging & Monitoring

Environment Variables by Use Case

Minimal Setup (New Installation)

Production Deployment

Self-Hosted Behind Reverse Proxy

Corporate Environment (Behind Proxy)

High-Performance Deployment

Debugging

Validation

Notes

Quick Setup Checklist

Legacy: AI Provider Environment Variables (Deprecated)

12 KiB

Raw Blame History