Open Notebook Deployment Best Practices: A Production Guide

The most reliable way to deploy Open Notebook in production is to use the official multi‑container Docker Compose setup, secure secrets via a docker.env file, and place the stack behind a reverse proxy.

Open Notebook is an open‑source notebook application built as a three‑tier system (frontend → API → SurrealDB). In the lfnovo/open-notebook repository, the maintainers provide hardened Docker assets and detailed configuration guides that make scaling and securing the stack straightforward. Following the project’s documented best practices ensures each service remains isolated, upgradable, and safe for production traffic.

Choose the Right Open Notebook Deployment Mode

The repository supports three installation paths, but not all are intended for production use.

• Docker Compose multi‑container — The default and recommended mode. It isolates SurrealDB and the Open Notebook services on the internal Docker network, lets you scale components independently, and works identically on macOS, Linux, and Windows. See the official guide at docs/1-INSTALLATION/docker-compose.md.
• Single‑container (legacy) — Deprecated and slated for removal. Only consider this if you have extremely constrained resources and can accept reduced flexibility. Documentation lives in docs/1-INSTALLATION/single-container.md.
• From source — Reserved for developers who need to modify the codebase, run unit tests, or integrate custom services. Refer to docs/1-INSTALLATION/from-source.md.

Always start with the Docker Compose route; the single‑container option is scheduled for deprecation in a future release.

Secure the Production Environment

Before starting the stack, harden the environment variables stored in docker.env. Never commit this file to source control.

Generate a Strong Encryption Key

The OPEN_NOTEBOOK_ENCRYPTION_KEY variable protects stored API credentials inside the database. Generate a long random secret and add it to docker.env:

# docker.env

OPEN_NOTEBOOK_ENCRYPTION_KEY=your-random-32-char-secret

Without this key, the API container will fail to start.

Harden Database Credentials

The default SurrealDB credentials (root / root) are acceptable for local testing but must be changed for any production deployment. Update SURREAL_USER and SURREAL_PASSWORD in docker.env to strong, unique values.

Restrict Network Exposure

Keep the Open Notebook API on the internal Docker network and expose only the UI port (8502) to external traffic. For public deployments, terminate TLS at a reverse proxy and forward traffic to the internal services. See docs/5-CONFIGURATION/reverse-proxy.md for Nginx, Traefik, and Caddy recipes.

Configure and Start the Docker Stack

Create a docker.env file (or copy the repository template at .env.example) with the minimal variables required for production:

# docker.env – minimal production settings

OPEN_NOTEBOOK_ENCRYPTION_KEY=super-secret-key
SURREAL_URL=ws://surrealdb:8000/rpc
SURREAL_USER=admin
SURREAL_PASSWORD=very-strong-pwd
SURREAL_NAMESPACE=open_notebook
SURREAL_DATABASE=open_notebook

Start all services in detached mode using the multi‑container profile:

docker compose --profile multi up -d

Verify that SurrealDB and Open Notebook are healthy:

docker ps | grep -E 'surrealdb|open_notebook'
docker compose logs -f surrealdb
docker compose logs -f open_notebook

If the API container exits immediately, inspect the logs for missing environment variables:

docker compose logs open_notebook

The project’s root docker-compose.yml defines the production topology. It mounts persistent volumes for SurrealDB and application data, enforces service restart policies, and links the open_notebook service to the SurrealDB container via the internal network.

Add AI Provider Credentials After Startup

The UI cannot generate responses until at least one provider credential is registered. After the containers are running:

1. Open the UI at http://localhost:8502.
2. Navigate to Settings → API Keys → Add Credential.
3. Select a provider (for example, OpenAI, Anthropic, or Ollama) and paste the API key.
4. Click Test Connection, then Discover Models, and finally Register Models.

The UI encrypts the key at rest using the OPEN_NOTEBOOK_ENCRYPTION_KEY set earlier, so the secret never appears in plain text on disk.

Place Open Notebook Behind a Reverse Proxy

For public‑facing hosts, terminate TLS at the proxy and forward traffic to the internal ports. Below is a minimal Nginx server block:

# Example snippet for an Nginx reverse proxy

server {
    listen 443 ssl;
    server_name notebook.example.com;

    location / {
        proxy_pass http://localhost:8502;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /api/ {
        proxy_pass http://localhost:5055;
        proxy_set_header Host $host;
    }
}

A reverse proxy also enables HTTP/2, rate limiting, and IP‑based access controls. The full configuration reference is maintained in docs/5-CONFIGURATION/reverse-proxy.md.

Monitor, Update, and Tune Resources

Ongoing maintenance keeps the deployment stable and secure.

• Centralize logs — Use docker compose logs -f for real‑time debugging. For long‑term retention, pipe logs into a central system such as Loki or the ELK stack.
• Enable health checks — Add Docker health checks in docker-compose.yml if you require automatic restarts when a service becomes unhealthy.
• Update with minimal downtime — Pull the latest image and recreate the stack:

docker pull lfnovo/open_notebook:latest
docker compose up -d --force-recreate

• Tune resources — Increase container CPU and memory limits in docker-compose.yml for heavy workloads, such as large LLM inference calls or batch embedding jobs.

Fix Common Deployment Pitfalls

Recognizing failure patterns early reduces troubleshooting time.

• API cannot start — Usually caused by a missing OPEN_NOTEBOOK_ENCRYPTION_KEY. Add the key to docker.env and restart the stack.
• No models appear in the UI — Indicates a missing provider credential or a failed test connection. Complete the credential setup in Settings → API Keys.
• Connection refused to SurrealDB — Verify that the SURREAL_URL uses the internal Docker hostname (ws://surrealdb:8000/rpc) and that the SurrealDB container is running (docker compose ps).
• High memory usage — Often triggered by large local model downloads, such as Ollama weights. Mount a persistent volume for the model cache or limit the model size.

Detailed remediation steps are documented in docs/6-TROUBLESHOOTING/quick-fixes.md.

Summary

• Use Docker Compose as the default deployment mode; avoid the legacy single‑container path.
• Protect secrets by setting a strong OPEN_NOTEBOOK_ENCRYPTION_KEY and changing the default SurrealDB credentials in docker.env.
• Expose only the UI port publicly, and run the stack behind a reverse proxy terminating TLS.
• Bootstrap the system by adding an AI provider credential through the Settings UI after the containers start.
• Maintain the stack with health checks, centralized logging, and regular image updates via docker pull.

Frequently Asked Questions

Is the single-container deployment still supported?

No. According to the lfnovo/open-notebook source docs, the single‑container mode is deprecated and will be removed in a future release. New deployments should rely on the multi‑container Docker Compose setup defined in the root docker-compose.yml.

What happens if I forget to set OPEN_NOTEBOOK_ENCRYPTION_KEY?

The Open Notebook API container will exit during startup and report an error in the Docker logs. This key is mandatory because it encrypts every stored provider credential inside SurrealDB.

Can I use a remote SurrealDB instance instead of the Docker Compose service?

Yes. Update SURREAL_URL inside docker.env to point to your remote instance, and remove or disable the local surrealdb service in docker-compose.yml. The docs/5-CONFIGURATION/index.md file covers additional database configuration options.

How do I update Open Notebook without losing data?

Run docker pull lfnovo/open_notebook:latest followed by docker compose up -d --force-recreate. Because docker-compose.yml mounts persistent volumes for SurrealDB and notebook data, your database contents and uploaded files survive the container recreation.

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