Merge pull request #723 from lfnovo/docs/deprecate-single-container

docs: deprecate single-container image

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -58,7 +58,7 @@ body:
       description: Which version are you using?
       options:
         - v1-latest (Docker)
-        - v1-latest-single (Docker)
+        - v1-latest-single (Docker, deprecated)
         - Latest from main branch
         - Other (please specify in additional context)
     validations:

.github/ISSUE_TEMPLATE/installation_issue.yml

@@ -30,8 +30,8 @@ body:
       label: Installation Method
       description: How are you trying to install Open Notebook?
       options:
-        - Docker (single container - v1-latest-single)
+        - Docker (docker-compose - recommended)
-        - Docker (multi-container - docker-compose)
+        - Docker (single container - v1-latest-single, deprecated)
         - Local development (make start-all)
         - Other (please specify below)
     validations:

docs/0-START-HERE/quick-start-local.md

@@ -38,7 +38,7 @@ services:
       - ./surreal_data:/mydata
 
   open_notebook:
-    image: lfnovo/open_notebook:v1-latest-single
+    image: lfnovo/open_notebook:v1-latest
     pull_policy: always
     ports:
       - "8502:8502"  # Web UI (React frontend)
@@ -55,7 +55,6 @@ services:
       - SURREAL_DATABASE=open_notebook
     volumes:
       - ./notebook_data:/app/data
-      - ./surreal_data:/mydata
     depends_on:
       - surrealdb
     restart: always

docs/1-INSTALLATION/docker-compose.md

@@ -327,7 +327,7 @@ docker compose up -d
 Looking for different configurations? Check out our [examples/](../../examples/) folder:
 
 - **[Ollama Setup](../../examples/docker-compose-ollama.yml)** - Run local AI models (free, private)
-- **[Single Container](../../examples/docker-compose-single.yml)** - All-in-one container (deprecated, not recommended)
+- **[Single Container](../../examples/docker-compose-single.yml)** - All-in-one container (deprecated, will be removed in v2)
 - **[Development](../../examples/docker-compose-dev.yml)** - For contributors and developers
 
 Each example includes detailed comments and usage instructions.

docs/1-INSTALLATION/index.md

@@ -14,13 +14,10 @@ Choose your installation route based on your setup and use case.
 
 ---
 
-### 🏠 I want everything in one container (Simplified)
+### 🏠 I want everything in one container (Deprecated)
-**→ [Single Container](single-container.md)** - All-in-one for simple deployments
+**→ [Single Container](single-container.md)** - Deprecated, will be removed in v2
-- ✅ Minimal configuration
+- ⚠️ **Deprecated** — please use Docker Compose instead
-- ✅ Lower resource usage
+- Still supported until v2 release
-- ✅ Good for shared hosting
-- ✅ Works on PikaPods, Railway, etc.
-- ⏱️ 3 minutes to running
 
 ---
 
@@ -80,7 +77,7 @@ Choose your installation route based on your setup and use case.
 **Already know which way to go?** Pick your installation path:
 
 - [Docker Compose](docker-compose.md) - **Most users**
-- [Single Container](single-container.md) - **Shared hosting**
+- [Single Container](single-container.md) - **Deprecated**
 - [From Source](from-source.md) - **Developers**
 
 > **Privacy-first?** Any installation method works with Ollama for 100% local AI. See [Local Quick Start](../0-START-HERE/quick-start-local.md).
@@ -102,7 +99,7 @@ Before installing, you'll need:
 
 ### For Docker Users
 1. Install [Docker Desktop](https://docker.com/products/docker-desktop)
-2. Choose: [Docker Compose](docker-compose.md) or [Single Container](single-container.md)
+2. Follow [Docker Compose](docker-compose.md) installation
 3. Follow the step-by-step guide
 4. Access at `http://localhost:8502`
 

docs/1-INSTALLATION/single-container.md

@@ -1,4 +1,6 @@
-# Single Container Installation
+# 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](docker-compose.md), 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.**
 
@@ -6,8 +8,6 @@ All-in-one container setup. **Simpler than Docker Compose, but less flexible.**
 
 > **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`).
 
-> **Note**: While this is a simple way to get started, we recommend [Docker Compose](docker-compose.md) for most users. Docker Compose is more flexible and will make it easier if we add more services to the setup in the future. This single-container option is best for platforms that specifically require it (PikaPods, Railway, etc.).
-
 ## Prerequisites
 
 - Docker installed (for local testing)

docs/5-CONFIGURATION/ollama.md

@@ -85,9 +85,10 @@ ollama serve
 On Linux, `host.docker.internal` doesn't resolve automatically like it does on macOS/Windows. You must add `extra_hosts` to your docker-compose.yml:
 
 ```yaml
+# Add to your docker-compose.yml (requires surrealdb service, see installation guide)
 services:
   open_notebook:
-    image: lfnovo/open_notebook:v1-latest-single
+    image: lfnovo/open_notebook:v1-latest
     # ... other settings ...
     extra_hosts:
       - "host.docker.internal:host-gateway"
@@ -117,10 +118,11 @@ When both Open Notebook and Ollama run in the same Docker Compose stack:
 **Docker Compose Example:**
 
 ```yaml
-version: '3.8'
+# Requires surrealdb service — see full base setup:
+# https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml
 services:
   open-notebook:
-    image: lfnovo/open_notebook:v1-latest-single
+    image: lfnovo/open_notebook:v1-latest
     pull_policy: always
     ports:
       - "8502:8502"
@@ -129,7 +131,6 @@ services:
       - OPEN_NOTEBOOK_ENCRYPTION_KEY=change-me-to-a-secret-string
     volumes:
       - ./notebook_data:/app/data
-      - ./surreal_data:/mydata
     depends_on:
       - ollama
 
@@ -425,9 +426,10 @@ ollama run gemma3:12b "Hello, world"
 If you see `Name or service not known` errors on Linux, add `extra_hosts` to your docker-compose.yml:
 
 ```yaml
+# Add to your docker-compose.yml (requires surrealdb service, see installation guide)
 services:
   open_notebook:
-    image: lfnovo/open_notebook:v1-latest-single
+    image: lfnovo/open_notebook:v1-latest
     extra_hosts:
       - "host.docker.internal:host-gateway"
     environment:
@@ -441,7 +443,7 @@ This maps `host.docker.internal` to your host machine's IP. macOS/Windows Docker
 **2. Host networking on Linux (alternative):**
 ```bash
 # Use host networking if host.docker.internal doesn't work
-docker run --network host lfnovo/open_notebook:v1-latest-single
+docker run --network host lfnovo/open_notebook:v1-latest  # for quick testing only
 ```
 Then in **Settings → API Keys**, use base URL: `http://localhost:11434`
 
@@ -568,9 +570,10 @@ export ESPERANTO_SSL_VERIFY=false
 
 **Docker Compose example with SSL configuration:**
 ```yaml
+# Add to your docker-compose.yml (requires surrealdb service, see installation guide)
 services:
   open-notebook:
-    image: lfnovo/open_notebook:v1-latest-single
+    image: lfnovo/open_notebook:v1-latest
     pull_policy: always
     environment:
       - OPEN_NOTEBOOK_ENCRYPTION_KEY=change-me-to-a-secret-string

docs/5-CONFIGURATION/openai-compatible.md

@@ -158,6 +158,7 @@ In **Settings → API Keys**, add an **OpenAI-Compatible** credential with base
 ### Docker Compose Example
 
 ```yaml
+# Add to your docker-compose.yml (requires surrealdb service, see installation guide)
 services:
   text-gen:
     image: atinoda/text-generation-webui:default
@@ -169,7 +170,7 @@ services:
     command: --api --listen
 
   open-notebook:
-    image: lfnovo/open_notebook:v1-latest-single
+    image: lfnovo/open_notebook:v1-latest
     pull_policy: always
     depends_on:
       - text-gen
@@ -196,6 +197,7 @@ In **Settings → API Keys**, add an **OpenAI-Compatible** credential with base
 ### Docker Compose with GPU
 
 ```yaml
+# Add to your docker-compose.yml (requires surrealdb service, see installation guide)
 services:
   vllm:
     image: vllm/vllm-openai:latest
@@ -213,7 +215,7 @@ services:
               capabilities: [gpu]
 
   open-notebook:
-    image: lfnovo/open_notebook:v1-latest-single
+    image: lfnovo/open_notebook:v1-latest
     pull_policy: always
     depends_on:
       - vllm

docs/5-CONFIGURATION/reverse-proxy.md

@@ -75,9 +75,11 @@ Caddy handles HTTPS automatically. The timeout settings ensure long-running oper
 ### Traefik
 
 ```yaml
+# Add this to your docker-compose.yml alongside the surrealdb service
+# See full base setup: https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml
 services:
   open-notebook:
-    image: lfnovo/open_notebook:v1-latest-single
+    image: lfnovo/open_notebook:v1-latest
     pull_policy: always
     environment:
       - API_URL=https://notebook.example.com
@@ -106,7 +108,7 @@ serversTransport:
 
 ### Coolify
 
-1. Create new service with `lfnovo/open_notebook:v1-latest-single`
+1. Create new service using [Docker Compose](../1-INSTALLATION/docker-compose.md)
 2. Set port to **8502**
 3. Add environment: `API_URL=https://your-domain.com`
 4. Enable HTTPS in Coolify
@@ -159,10 +161,12 @@ When `API_URL` is not set, the Next.js frontend:
 
 ## Complete Docker Compose Example
 
+> **Note:** This example only shows the open-notebook and nginx services. You also need a `surrealdb` service. See the [full base docker-compose.yml](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml) for the complete setup.
+
 ```yaml
 services:
   open-notebook:
-    image: lfnovo/open_notebook:v1-latest-single
+    image: lfnovo/open_notebook:v1-latest
     pull_policy: always
     container_name: open-notebook
     environment:
@@ -171,7 +175,6 @@ services:
       - OPEN_NOTEBOOK_PASSWORD=${OPEN_NOTEBOOK_PASSWORD}
     volumes:
       - ./notebook_data:/app/data
-      - ./surreal_data:/mydata
     # Only expose to localhost (nginx handles public access)
     ports:
       - "127.0.0.1:8502:8502"
@@ -304,9 +307,10 @@ API_URL=http://192.168.1.100:5055
 
 **Step 3: Expose ports**
 ```yaml
+# Add to your docker-compose.yml (requires surrealdb service, see installation guide)
 services:
   open-notebook:
-    image: lfnovo/open_notebook:v1-latest-single
+    image: lfnovo/open_notebook:v1-latest
     pull_policy: always
     environment:
       - API_URL=http://192.168.1.100:5055
@@ -334,9 +338,10 @@ Host the API and frontend on different subdomains:
 
 **docker-compose.yml:**
 ```yaml
+# Add to your docker-compose.yml (requires surrealdb service, see installation guide)
 services:
   open-notebook:
-    image: lfnovo/open_notebook:v1-latest-single
+    image: lfnovo/open_notebook:v1-latest
     pull_policy: always
     environment:
       - API_URL=https://api.notebook.example.com
@@ -465,7 +470,7 @@ http {
 }
 ```
 
-**Note**: Most users should use the single-container approach (`v1-latest-single`). Multi-container is only needed for custom scaling or isolation requirements.
+**Note**: Most users should use the [Docker Compose](../1-INSTALLATION/docker-compose.md) approach (`v1-latest`). Multi-container with separate nginx is only needed for custom scaling or isolation requirements.
 
 ---
 

docs/5-CONFIGURATION/security.md

@@ -82,10 +82,10 @@ environment:
 ### Docker Deployment
 
 ```yaml
-# docker-compose.yml
+# Add to your docker-compose.yml (requires surrealdb service, see installation guide)
 services:
   open_notebook:
-    image: lfnovo/open_notebook:v1-latest-single
+    image: lfnovo/open_notebook:v1-latest
     pull_policy: always
     environment:
       - OPEN_NOTEBOOK_ENCRYPTION_KEY=your-secret-encryption-key
@@ -245,9 +245,10 @@ async function getNotebooks() {
 ### Docker Security
 
 ```yaml
+# Add to your docker-compose.yml (requires surrealdb service, see installation guide)
 services:
   open_notebook:
-    image: lfnovo/open_notebook:v1-latest-single
+    image: lfnovo/open_notebook:v1-latest
     pull_policy: always
     ports:
       - "127.0.0.1:8502:8502"  # Bind to localhost only

docs/index.md

@@ -17,7 +17,7 @@ Welcome to Open Notebook - a privacy-focused AI research assistant. This documen
 - Multiple installation routes
 - Docker Compose (recommended)
 - From source (developers)
-- Single container (shared hosting)
+- ~~Single container~~ (deprecated, see Docker Compose)
 
 ### I want to understand how it works
 → Read this: **[2-CORE-CONCEPTS](2-CORE-CONCEPTS/index.md)**
@@ -77,7 +77,7 @@ Welcome to Open Notebook - a privacy-focused AI research assistant. This documen
 
 **[1-INSTALLATION](1-INSTALLATION/index.md)** — Getting it running
 - Multiple installation routes
-- Docker, single-container, from-source
+- Docker Compose (recommended), from-source
 - Requirements and setup
 
 **[2-CORE-CONCEPTS](2-CORE-CONCEPTS/index.md)** — Understanding the system