AI Tools

Self-Hosting Open Notebook: Docker Deployment, Model Setup, and Data Security

Self-host Open Notebook with Docker Compose, secure its encryption key and database credentials, configure cloud or local models, and validate the deployment through container status, logs, and test sources.

Open Notebook is an open-source application for research and source-based learning. It can ingest PDFs, web pages, audio, video, and Office documents, then provide search, chat, note organization, and podcast generation around those sources. Unlike a general chatbot, it keeps sources, citations, model settings, and notes in your own workspace.

Self-hosting does not automatically mean fully offline. When you choose OpenAI, Anthropic, Google, or another cloud model, the context sent to that model still leaves your server. Keeping the processing chain local requires both a self-hosted application and local models.

Prerequisites

The official quick start requires Docker Desktop. A Linux server can use Docker Engine and the Compose plugin. Verify both commands first:

1
2

docker --version
docker compose version

You should also prepare:

  • A persistent directory for database and application data.
  • A random OPEN_NOTEBOOK_ENCRYPTION_KEY.
  • A domain, HTTPS, and access control if the service will be exposed.
  • API credentials for a cloud model, or a reachable Ollama/LM Studio service.

Download the official Compose file

Use a dedicated directory so that data files do not spread across an unrelated project:

1
2
3

mkdir open-notebook
cd open-notebook
curl -o docker-compose.yml https://raw.githubusercontent.com/lfnovo/open-notebook/main/docker-compose.yml

Avoid copying an old Compose example from a blog post. Images, ports, and database settings may change, so use the current file from the official repository.

Settings that must be changed before startup

Set the encryption key in docker-compose.yml or the associated .env file:

1

OPEN_NOTEBOOK_ENCRYPTION_KEY=replace-this-with-your-own-long-random-string

The key protects API credentials stored in the database. Do not change it casually after deployment, because previously stored credentials may no longer decrypt.

The official local example allows SurrealDB to use root:root, but that is only suitable for a test instance bound to localhost. For LAN or public deployment, set a database user and password as well:

1
2

SURREAL_USER=open_notebook_user
SURREAL_PASSWORD=replace-this-with-a-long-random-password

Keep the database debugging port bound to 127.0.0.1:8000. Do not change it to 0.0.0.0:8000 merely for convenience.

Start and inspect the containers 

1
2

docker compose up -d
docker compose ps

After the containers have started, open:

1

http://localhost:8502

Port 8502 is the web UI, 5055 is the REST API, and 8000 is the local SurrealDB debugging port. docker compose ps should show both the application and database containers running.

If the page does not open, inspect the logs first:

1
2

docker compose logs --tail=100 open_notebook
docker compose logs --tail=100 surrealdb

Configure the first model

In the web interface:

  1. Open Models.
  2. Select OpenAI, Anthropic, Google, Ollama, LM Studio, or another supported provider.
  3. Add the API key or local service address.
  4. Click Test to verify the connection.
  5. Click Sync Models and select the models you actually intend to use.
  6. Use Default Model Assignments to assign defaults automatically or manually.

Not every provider supports LLM, embeddings, speech-to-text, and text-to-speech at the same time. If chat works but source retrieval fails, check the embedding model instead of repeatedly replacing the chat model.

Validate with one small source set

Do not import your entire archive immediately. Create a test notebook and add only:

  1. A short text-based PDF.
  2. One public web page.
  3. One manually written test note.

Then verify:

  • The sources finish processing.
  • Search finds a distinctive sentence from the PDF.
  • Answers display a source or citation.
  • A newly created note can be reopened.
  • The sources remain after the containers restart.

The last check confirms that persistent directories such as surreal_data and notebook_data are working.

Common problems

Port 8502 is already in use

Change the host-side port in Compose, for example:

1
2

ports:
  - "18502:8502"

Then open http://localhost:18502. The internal container port remains 8502.

The database keeps restarting

Inspect the SurrealDB logs first. On Linux, common causes include a mounted directory without write permission or database files created by an incompatible image version. Back up the data directory before changing permissions, and do not delete persistent data as the first troubleshooting step.

The provider test passes, but Q&A fails

Check the default LLM, embedding model, and source-processing status in that order. For a private model server, also confirm that the container can reach the host. localhost inside a container refers to that container, not necessarily the machine running Ollama or LM Studio.

Updating and backing up

Before updating, back up the Compose file, .env, database data, and application data. Then run:

1
2
3

docker compose pull
docker compose up -d
docker compose ps

Backing up only docker-compose.yml is not enough. Recovery depends on the persistent data, encryption key, and database credentials.

Open Notebook or NotebookLM?

NotebookLM is simpler if you want a hosted service without maintaining a server and are comfortable with Google hosting. Open Notebook is a better fit when you need self-hosting, several model providers, a REST API, custom workflows, or local models. The tradeoff is that you become responsible for upgrades, backups, access control, and model costs.

References