How to Back Up Your Open Notebook Data: Complete File-Based Backup Guide

To back up Open Notebook data, create a compressed archive of the surreal_data/ and data/ directories along with your secret.key and .env configuration file, then restore by extracting the archive into the repository root and restarting the services.

Open Notebook stores all user-generated content locally using a file-first architecture built on SurrealDB and the host filesystem. Because the application persists notebooks, sources, uploads, and vector embeddings directly to disk—rather than relying on external cloud APIs—you can perform a complete backup using standard Unix archiving tools. This guide shows you how to safeguard your research data using the exact file paths and methods defined in the official lfnovo/open-notebook source code.

What Files You Need to Back Up

Open Notebook organizes persistent data across four critical locations on the filesystem. According to the project's docker-compose.yml and runtime configuration, backing up these directories ensures you capture the complete logical state of every notebook, source, and generated artifact:

• surreal_data/ – Contains the raw SurrealDB database files that store notebooks, sources, notes, and vector embeddings. This directory is mounted as a volume in the Docker Compose configuration.
• data/uploads/ – Stores all user-uploaded files including PDFs, DOCX documents, images, audio, and video attachments.
• data/podcasts/ – Holds audio files generated by the podcast pipeline.
• secret.key – The encryption key generated on first run that secures stored credentials. Losing this file renders all encrypted credentials unreadable.
• .env – Your environment configuration file containing OPEN_NOTEBOOK_PASSWORD and other deployment-specific variables.

Step-by-Step Backup Guide

Stop the Services

Before creating an archive, stop the running containers to ensure the SurrealDB files are in a consistent state and not actively being written to.

docker compose down

Create a Timestamped Archive

Run the following command from the repository root to create a compressed tarball containing all persistent data:

BACKUP_FILE="backup-$(date +%Y%m%d-%H%M%S).tar.gz"
tar -czf "$BACKUP_FILE" data/ surreal_data/ secret.key .env

echo "Backup saved to $BACKUP_FILE"

This command archives the database files, user uploads, generated podcasts, encryption key, and environment variables into a single file with a timestamp suffix.

Secure the Encryption Key

Store the secret.key file in a separate, secure location such as a password manager or encrypted USB drive. According to the API configuration in lfnovo/open-notebook, this key is essential for decrypting stored credentials, and losing it will lock you out of any integrated services.

How to Restore Open Notebook Data

Extract the Archive

To restore from a backup, navigate to the repository root and extract the tarball. This overwrites the existing data/ and surreal_data/ directories with your backed-up versions:

tar -xzf backup-20240401-120000.tar.gz

Restart the Stack

Once the files are extracted, restart the services. SurrealDB will automatically detect the restored database files in surreal_data/ and load the previous state:

docker compose up -d

The FastAPI layer in api/main.py connects to SurrealDB via the async driver and will immediately serve the restored notebooks and sources.

Automated Daily Backups with Cron

For production deployments, automate backups using a cron job. The following entry runs daily at 2:00 AM, creating a timestamped archive in /backups/:

0 2 * * * root cd /path/to/open-notebook && \
  /usr/bin/tar -czf "/backups/ob-$(date +\%Y\%m\%d).tar.gz" data/ surreal_data/ secret.key .env

Rotate these archives weekly or monthly to prevent disk space exhaustion, and consider encrypting sensitive backups using gpg -c before storing them on cloud drives.

Summary

• Open Notebook persists all data locally in surreal_data/ (database) and data/ (uploads and podcasts).
• Complete backups require archiving both directories plus secret.key and .env using tar.
• Always stop services with docker compose down before backing up to ensure database consistency.
• Restore by extracting the archive into the repository root and restarting the stack.
• Protect the encryption key separately; losing secret.key makes stored credentials permanently inaccessible.

Frequently Asked Questions

Where does Open Notebook store my data?

Open Notebook stores data in three primary locations on the host filesystem: the surreal_data/ directory contains the SurrealDB database files, data/uploads/ contains user-uploaded files like PDFs and images, and data/podcasts/ contains generated audio files. Additionally, the secret.key file stores encryption credentials and the .env file stores configuration variables.

Can I back up Open Notebook while it is running?

You should not back up Open Notebook while services are running. The official documentation recommends stopping the Docker Compose stack first to ensure the SurrealDB files in surreal_data/ are not in the middle of a write operation, which could result in a corrupted backup. Use docker compose down before creating your archive.

What happens if I lose my secret.key file?

If you lose the secret.key file generated on first run, all encrypted credentials stored in the database become permanently unreadable. This file is required to decrypt sensitive configuration data, and Open Notebook does not provide a recovery mechanism. Always store this key in a secure, separate location from your main backups.

How do I migrate my Open Notebook instance to a new server?

To migrate, create a backup archive on the source server using tar -czf, transfer the file to the new server, and extract it into a fresh clone of the lfnovo/open-notebook repository. Ensure you copy the secret.key and .env files, then run docker compose up -d to start the services. The new instance will contain all notebooks, sources, and uploaded files from the original deployment.

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