Quick Start - External Ollama

Run Open Notebook with a separately installed Ollama (not via Docker). This avoids Docker running the Ollama service while you use your own local Ollama installation.

Prerequisites

1. Docker Desktop installed (for SurrealDB and Open Notebook)

   • Download here

2. Ollama installed separately

   • Download here
   • Verify: run ollama --version

3. Models downloaded in Ollama:

   bashCopy

   ollama pull mistral
   ollama pull nomic-embed-text
   

Step 1: Start Ollama (1 min)

Start the Ollama server:

# Default: runs on http://localhost:11434
ollama serve

Keep this terminal open. Ollama will run in the background.

Optional: Start Ollama on a custom port or network interface:

OLLAMA_HOST=0.0.0.0:11434 ollama serve

Step 2: Create Configuration (1 min)

Create a new folder open-notebook-external-ollama and add these files:

docker-compose.yml:

services:
  surrealdb:
    image: surrealdb/surrealdb:v2
    command: start --user root --pass password --bind 0.0.0.0:8000 rocksdb:/mydata/mydatabase.db
    user: root
    ports:
      - "8000:8000"
    volumes:
      - ./surreal_data:/mydata

  open_notebook:
    image: lfnovo/open_notebook:v1-latest
    pull_policy: always
    ports:
      - "8502:8502"  # Web UI (React frontend)
      - "5055:5055"  # API (required!)
    environment:
      # Encryption key for credential storage (required)
      - OPEN_NOTEBOOK_ENCRYPTION_KEY=change-me-to-a-secret-string

      # Database (required)
      - SURREAL_URL=ws://surrealdb:8000/rpc
      - SURREAL_USER=root
      - SURREAL_PASSWORD=password
      - SURREAL_NAMESPACE=open_notebook
      - SURREAL_DATABASE=open_notebook
    volumes:
      - ./notebook_data:/app/data
    depends_on:
      - surrealdb
    restart: always

Note: No Ollama service in Docker — we use the host's Ollama.

Step 3: Connect Open Notebook to Host Ollama (1 min)

When Open Notebook runs inside Docker, it cannot reach localhost:11434 on your host directly. Use the special hostname:

Step 4: Start Open Notebook (1 min)

Open terminal in your open-notebook-external-ollama folder:

docker compose up -d

Wait 10-15 seconds for services to start.

Step 5: Configure Ollama Provider (1 min)

1. Go to Settings → API Keys
2. Click Add Credential
3. Select provider: Ollama
4. Give it a name (e.g., "Local Ollama")
5. Enter the base URL:
   • Windows/macOS: http://host.docker.internal:11434
   • Linux: http://host.containers.internal:11434
6. Click Save
7. Click Test Connection — should show success
8. Click Discover Models → Register Models

Step 6: Configure Models (1 min)

1. Go to Settings → Models
2. Set:
   • Language Model: ollama/mistral (or whichever model you downloaded)
   • Embedding Model: ollama/nomic-embed-text
3. Click Save

Step 7: Access Open Notebook (instant)

Open your browser:

http://localhost:8502

Verification Checklist

• Ollama is running (ollama serve in terminal)
• Docker is running
• You can access http://localhost:8502
• Ollama credential is configured with host URL and tested
• Models are registered
• Chat works

Troubleshooting

"Connection failed" when testing Ollama credential

1. Verify Ollama is running:

   bashCopy

   curl http://localhost:11434/api/version
   

2. Check firewall allows local connections on port 11434

3. For Windows/macOS, ensure host.docker.internal is reachable from inside the container:

   bashCopy

   docker exec <open_notebook_container> curl http://host.docker.internal:11434/api/version
   

Ollama not starting

# Check Ollama logs
ollama list

# Pull a model again
ollama pull mistral

"Address already in use" for SurrealDB

docker compose down
docker compose up -d

Why External Ollama?

External Ollama is recommended if you:

• Already have Ollama installed and configured
• Want GPU access without Docker GPU passthrough complexity
• Prefer managing models via command line directly

Going Further

• Add more models: Run ollama pull <model>, then re-discover from Open Notebook
• Check Ollama status: ollama list shows downloaded models
• Customize Ollama: Edit ~/.ollama/config.yaml for advanced settings

Need Help? Join our Discord community