# Open Notebook Deployment Best Practices: A Production Guide

> Deploy Open Notebook in production using Docker Compose secrets and a reverse proxy. Follow our guide for a reliable and secure setup. Learn best deployment practices today.

- Repository: [Luis Novo/open-notebook](https://github.com/lfnovo/open-notebook)
- Tags: best-practices
- Published: 2026-06-05

---

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

```text

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

```text

# 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:

```bash
docker compose --profile multi up -d

```

Verify that SurrealDB and Open Notebook are healthy:

```bash
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:

```bash
docker compose logs open_notebook

```

The project’s root [`docker-compose.yml`](https://github.com/lfnovo/open-notebook/blob/main/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:

```nginx

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

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

```

- **Tune resources** — Increase container CPU and memory limits in [`docker-compose.yml`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml). The [`docs/5-CONFIGURATION/index.md`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml) mounts persistent volumes for SurrealDB and notebook data, your database contents and uploaded files survive the container recreation.