quick-start-external-ollama.md

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:

   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 rocksdb:/mydata/mydatabase.db
    user: root
    ports:
      # Localhost only — the database uses default credentials, so never
      # publish this port on 0.0.0.0
      - "127.0.0.1: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:

Host OS	Ollama URL in Open Notebook
Linux	http://host.containers.internal:11434
macOS	http://host.docker.internal:11434
Windows	http://host.docker.internal:11434

---

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 Manage → Models
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 Manage → 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:

   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:

   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?

Approach	Ollama in Docker	Ollama External
Resource isolation	Separated	Shares with host
GPU access	Requires Docker GPU setup	Native GPU access
Model management	Via docker exec	Via terminal directly
Memory usage	Isolated from host	Shared with host apps

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