open-notebook/docs/1-INSTALLATION/single-container.md

Single Container Installation (Deprecated)

Deprecation Notice: The single-container image (v1-latest-single) is deprecated and will be removed in v2. Please migrate to Docker Compose, which is the recommended installation method for all users. The single-container image will continue to receive updates until v2 is released, but no new features or documentation will target it.

All-in-one container setup. Simpler than Docker Compose, but less flexible.

Best for: PikaPods, Railway, shared hosting, minimal setups

Alternative Registry: Images available on both Docker Hub (lfnovo/open_notebook:v1-latest-single) and GitHub Container Registry (ghcr.io/lfnovo/open-notebook:v1-latest-single).

Prerequisites

• Docker installed (for local testing)
• API key from OpenAI, Anthropic, or another provider
• 5 minutes

Quick Setup

For Local Testing (Docker)

# docker-compose.yml
services:
  open_notebook:
    image: lfnovo/open_notebook:v1-latest-single
    pull_policy: always
    ports:
      - "8502:8502"  # Web UI (React frontend)
      - "5055:5055"  # API
    environment:
      - OPEN_NOTEBOOK_ENCRYPTION_KEY=change-me-to-a-secret-string
      - SURREAL_URL=ws://localhost:8000/rpc
      - SURREAL_USER=root
      - SURREAL_PASSWORD=root
      - SURREAL_NAMESPACE=open_notebook
      - SURREAL_DATABASE=open_notebook
    volumes:
      - ./data:/app/data
    restart: always

Run:

docker compose up -d

Access: http://localhost:8502

Then configure your AI provider:

1. Go to Settings → API Keys
2. Click Add Credential → Select your provider → Paste API key
3. Click Save, then Test Connection
4. Click Discover Models → Register Models

For Cloud Platforms

PikaPods:

1. Click "New App"
2. Search "Open Notebook"
3. Set environment variables (at minimum: OPEN_NOTEBOOK_ENCRYPTION_KEY)
4. Click "Deploy"
5. Open the app → Go to Settings → API Keys to configure your AI provider

Railway:

1. Create new project
2. Add lfnovo/open_notebook:v1-latest-single
3. Set environment variables (at minimum: OPEN_NOTEBOOK_ENCRYPTION_KEY)
4. Deploy
5. Open the app → Go to Settings → API Keys to configure your AI provider

Render:

1. Create new Web Service
2. Use Docker image: lfnovo/open_notebook:v1-latest-single
3. Set environment variables in dashboard (at minimum: OPEN_NOTEBOOK_ENCRYPTION_KEY)
4. Configure persistent disk for /app/data and /mydata

DigitalOcean App Platform:

1. Create new app from Docker Hub
2. Use image: lfnovo/open_notebook:v1-latest-single
3. Set port to 8502
4. Add environment variables (at minimum: OPEN_NOTEBOOK_ENCRYPTION_KEY)
5. Configure persistent storage

Heroku:

# Using heroku.yml
heroku container:push web
heroku container:release web
heroku config:set OPEN_NOTEBOOK_ENCRYPTION_KEY=your-secret-key

Coolify:

1. Add new service → Docker Image
2. Image: lfnovo/open_notebook:v1-latest-single
3. Port: 8502
4. Add environment variables (at minimum: OPEN_NOTEBOOK_ENCRYPTION_KEY)
5. Enable persistent volumes
6. Coolify handles HTTPS automatically

---

Environment Variables

Variable	Purpose	Example
OPEN_NOTEBOOK_ENCRYPTION_KEY	Encryption key for credentials (required)	my-secret-key
SURREAL_URL	Database	ws://localhost:8000/rpc
SURREAL_USER	DB user	root
SURREAL_PASSWORD	DB password	root
SURREAL_NAMESPACE	DB namespace	open_notebook
SURREAL_DATABASE	DB name	open_notebook
API_URL	External URL (for remote access)	https://myapp.example.com

AI provider API keys are configured via the Settings → API Keys UI after deployment.

---

Limitations vs Docker Compose

Feature	Single Container	Docker Compose
Setup time	2 minutes	5 minutes
Complexity	Minimal	Moderate
Services	All bundled	Separated
Scalability	Limited	Excellent
Memory usage	~800MB	~1.2GB

---

Next Steps

Same as Docker Compose setup - just access via http://localhost:8502 (local) or your platform's URL (cloud).

1. Go to Settings → API Keys to add your AI provider credential
2. Test Connection and Discover Models

See Docker Compose for full post-install guide.