open-notebook/docs/single-container-deployment.md

Single-Container Deployment Guide

For users who prefer an all-in-one container solution (e.g., PikaPods, simple deployments), Open Notebook provides a single-container image that includes all services: SurrealDB, API backend, background worker, and Streamlit UI.

Overview

The single-container deployment packages:

• SurrealDB: Database service
• FastAPI: REST API backend
• Background Worker: For podcast generation and transformations
• Streamlit: Web UI interface

All services are managed by supervisord with proper startup ordering.

Quick Start

Option 1: Using Docker Compose (Recommended)

1. Create a docker-compose.single.yml file:

services:
  open_notebook_single:
    image: lfnovo/open_notebook:latest-single
    ports:
      - "8502:8502"  # Streamlit UI
      - "5055:5055"  # REST API
    environment:
      # Add your API keys here
      - OPENAI_API_KEY=your_openai_key
      - ANTHROPIC_API_KEY=your_anthropic_key
      # ... other environment variables
    volumes:
      - ./notebook_data:/app/data          # Application data
      - ./surreal_single_data:/mydata      # SurrealDB data
    restart: always

2. Run the container:

docker compose -f docker-compose.single.yml up -d

Option 2: Direct Docker Run

docker run -d \
  --name open-notebook-single \
  -p 8502:8502 \
  -p 5055:5055 \
  -v ./notebook_data:/app/data \
  -v ./surreal_single_data:/mydata \
  -e OPENAI_API_KEY=your_openai_key \
  -e ANTHROPIC_API_KEY=your_anthropic_key \
  lfnovo/open_notebook:latest-single

Option 3: PikaPods Deployment

For PikaPods users, use the single-container image:

Image: lfnovo/open_notebook:latest-single
Port: 8502

Add your API keys as environment variables in the PikaPods configuration.

Environment Variables

The single-container deployment uses the same environment variables as the multi-container setup, but with SurrealDB configured for localhost connection:

# Database connection (automatically configured)
SURREAL_URL="ws://localhost:8000/rpc"
SURREAL_USER="root"
SURREAL_PASSWORD="root"
SURREAL_NAMESPACE="open_notebook"
SURREAL_DATABASE="staging"

# API Keys (configure these)
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
GEMINI_API_KEY=your_gemini_key
# ... other provider keys

Service Access

Once running, access the services at:

• Streamlit UI: http://localhost:8502
• REST API: http://localhost:5055
• API Documentation: http://localhost:5055/docs

Data Persistence

The single-container setup uses two volume mounts:

1. /app/data - Application data (notebooks, sources, etc.)
2. /mydata - SurrealDB database files

Make sure to mount these volumes to persist data between container restarts.

Security

For public deployments, always set the OPEN_NOTEBOOK_PASSWORD environment variable:

OPEN_NOTEBOOK_PASSWORD=your_secure_password

This protects both the Streamlit UI and REST API with password authentication.

Building from Source

To build the single-container image yourself:

# Clone the repository
git clone https://github.com/lfnovo/open-notebook
cd open-notebook

# Build the single-container image
make docker-build-single-dev

# Or build with multi-platform support
make docker-build-single

Troubleshooting

Container Won't Start

Check the logs to see which service is failing:

docker logs open-notebook-single

Database Connection Issues

The single-container uses localhost for SurrealDB. If you see connection errors, ensure:

1. The container has enough memory (minimum 1GB recommended)
2. No port conflicts on 8000 (SurrealDB internal port)
3. The /mydata volume is properly mounted and writable

Service Startup Order

Services start in this order:

1. SurrealDB (5 seconds startup time)
2. API Backend (3 seconds startup time)
3. Background Worker (3 seconds startup time)
4. Streamlit UI (5 seconds startup time)

If services fail to start, check the supervisord logs in the container.

Resource Requirements

Minimum Requirements:

• Memory: 1GB RAM
• CPU: 1 core
• Storage: 10GB (for data persistence)

Recommended:

• Memory: 2GB+ RAM
• CPU: 2+ cores
• Storage: 50GB+ (for larger datasets)

Differences from Multi-Container

Feature	Multi-Container	Single-Container
Database	Separate SurrealDB container	Built-in SurrealDB
Scaling	Can scale services independently	All services in one container
Resource Usage	More flexible resource allocation	Fixed resource sharing
Deployment	Requires docker-compose	Single container run
Complexity	More complex setup	Simpler deployment
Debugging	Easier to debug individual services	All logs in one container

When to Use Single-Container

Use single-container when:

• Deploying to platforms like PikaPods
• You want the simplest possible deployment
• Resource constraints favor single container
• You don't need to scale services independently

Use multi-container when:

• You need fine-grained resource control
• You want to scale services independently
• You prefer traditional microservices architecture
• You need to debug individual services easily