mirror of
https://github.com/lfnovo/open-notebook.git
synced 2026-08-10 17:46:48 +00:00
fcfd2afdb4
* fix(proxy): keep internal SurrealDB websocket out of HTTP proxy (#1160) websockets 15.0 auto-detects HTTP_PROXY/HTTPS_PROXY and tunnels even ws:// connections through the proxy. The SurrealDB SDK connects over a websocket, so with a proxy set the internal DB connection was routed through the external proxy, which rejected the internal host with HTTP 403 and killed the worker/API on startup. - Add ensure_internal_no_proxy() helper that merges host.docker.internal, surrealdb, localhost, 127.0.0.1 into no_proxy/NO_PROXY (never clobbering a user value) and call it at API, worker and DB-module startup. - Add host.docker.internal and surrealdb to the .env.example and docs NO_PROXY examples. - Add unit tests for the injection helper. * fix(proxy): preserve NO_PROXY wildcard and include custom SurrealDB host (#1160) Address review findings on the no_proxy injection: - NO_PROXY=* (bypass all hosts) is now treated as terminal: leave the user's config untouched instead of narrowing the wildcard to a finite list by appending the internal hosts. - Parse the SurrealDB host from SURREAL_URL (falling back to SURREAL_ADDRESS) and add it to the bypass list, so deployments with a custom DB host/IP no longer route DB traffic through the proxy. Unset or malformed values fall back to the four defaults gracefully. - Drop the inaccurate getproxies() caching remark in the test.
17 KiB
17 KiB
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. |
FRONTEND_BIND_HOST |
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. (Replaces HOSTNAME, which container runtimes such as Podman override with the container/pod hostname, causing Next.js to bind to the wrong address) |
API_HOST |
No | 0.0.0.0 (in Docker) |
Network interface for the API (uvicorn) to bind to. Set to :: for IPv6 dual-stack environments (listens on IPv6 and, on Linux defaults, IPv4 too) |
OPEN_NOTEBOOK_MAX_UPLOAD_SIZE_MB |
No | 100 | Maximum request body size (in MB) the API will accept, enforced before auth/routing. Raise this if you need to upload larger audio/video files. A fronting reverse proxy's own limit (e.g. nginx client_max_body_size) still applies and should be raised to match. |
Important:
OPEN_NOTEBOOK_ENCRYPTION_KEYis 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) |
Worker: Concurrency
| Variable | Required? | Default | Description |
|---|---|---|---|
OPEN_NOTEBOOK_WORKER_MAX_TASKS |
No | 5 | Maximum number of background tasks (source processing, embeddings, podcasts) the worker runs concurrently. Passed to the worker as --max-tasks at launch. Set to 1 for sequential processing on single-GPU or local-LLM setups, where parallel requests overload the model and trigger rate limits. |
Read at worker launch, from the process environment. In Docker this comes from the container environment — set it under
environment:indocker-compose.yml(or your orchestrator). For localmake worker-start/dev-init.sh, export it in your shell (e.g.export OPEN_NOTEBOOK_WORKER_MAX_TASKS=1) — it is consumed by the shell before the app loads.env, so a value placed only in.envwill not apply to these local launch paths.
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. |
OPEN_NOTEBOOK_MIN_CHUNK_SIZE |
No | 5 | Minimum chunk size in tokens. Chunks below this threshold are dropped before embedding to avoid degenerate single-character fragments that some providers (e.g. llama.cpp) return null embeddings for. Set to 0 to disable filtering. |
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) |
ESPERANTO_TTS_TIMEOUT |
No | 300 | Text-to-speech request timeout in seconds (passed through to Esperanto). Increase it for slow or self-hosted TTS providers that take longer than 5 minutes to synthesize a segment, otherwise long podcast segments can fail with a timeout. |
Content Extraction
| Variable | Required? | Default | Description |
|---|---|---|---|
FIRECRAWL_API_KEY |
No | None | Firecrawl API key for advanced web scraping |
FIRECRAWL_API_URL |
No | None | Base URL of a self-hosted Firecrawl instance (use instead of the hosted service) |
CCORE_FIRECRAWL_PROXY |
No | auto |
Firecrawl proxy mode to bypass anti-bot protection: basic, stealth, or auto |
CCORE_FIRECRAWL_WAIT_FOR |
No | 3000 |
Milliseconds Firecrawl waits for JavaScript to render before capturing the page |
JINA_API_KEY |
No | None | Jina AI API key for web extraction |
CRAWL4AI_API_URL |
No | None | Base URL of a remote Crawl4AI server. Set this to use Crawl4AI without a local install |
Optional heavy runtimes (installed on first startup)
These are off by default to keep the image lean. Setting one to true makes the container install that runtime the first time it starts (downloads are cached on the /app/data volume, so only the first boot is slow). See Content Processing Engines → Optional engines.
| Variable | Required? | Default | Description |
|---|---|---|---|
OPEN_NOTEBOOK_ENABLE_DOCLING |
No | false |
Install Docling on first startup: unlocks the docling document engine, the OCR toggle and image sources. Pulls a large ML stack. |
OPEN_NOTEBOOK_ENABLE_CRAWL4AI |
No | false |
Install the local Crawl4AI runtime + a Chromium browser on first startup: unlocks the crawl4ai URL engine. Not needed if CRAWL4AI_API_URL is set. |
Setup:
- Firecrawl: https://firecrawl.dev/
- Jina: https://jina.ai/
- Crawl4AI: https://github.com/unclecode/crawl4ai
The CCORE_FIRECRAWL_* variables are passed straight through to the content-core library (its settings are prefixed with CCORE_); Open Notebook itself doesn't read them. See Content Processing Engines for how these engines are selected in the UI.
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 (must include the internal DB hosts — see below) |
Route all outbound HTTP requests through a proxy server. Useful for corporate/firewalled environments.
Important:
NO_PROXYmust list the internal SurrealDB hosts —host.docker.internal(Docker) andsurrealdb(the compose service name). The SurrealDB SDK connects over a websocket, andwebsockets15.0+ tunnels evenws://connections through a configured proxy, which then rejects the internal host with HTTP 403 and prevents the API and worker from starting. Open Notebook injectshost.docker.internal,surrealdb,localhost,127.0.0.1intoNO_PROXYautomatically at startup as a safety net, but you should still set them explicitly.
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 (include the internal DB hosts!)
NO_PROXY=localhost,127.0.0.1,host.docker.internal,surrealdb,.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,host.docker.internal,surrealdb,.local
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-keynotOPEN_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_KEYin 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_URLif behind reverse proxy - Change
SURREAL_PASSWORDin 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 |
OMLX_API_BASE |
oMLX | Settings → API Keys → Add oMLX Credential |
OMLX_API_KEY |
oMLX | Optional; only if oMLX was started with --api-key |
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 |
NOVITA_API_KEY |
Novita | Settings → API Keys → Add Novita Credential |
PPQ_API_KEY |
PayPerQ (PPQ) | Settings → API Keys → Add PayPerQ Credential |
COHERE_API_KEY |
Cohere | Settings → API Keys → Add Cohere 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 |