mirror of https://github.com/lfnovo/open-notebook.git synced 2026-10-16 12:40:07 +00:00

docs: one canonical install path, first-run flow that ends in a working chat (#1459 )

* docs: one canonical install path, first-run flow that ends in a working chat

- Install guides download the shipped docker-compose.yml instead of pasting
  divergent copies; variants (Ollama in Docker, Ollama on the host, LM Studio)
  are shown as docker-compose.override.yml diffs.
- New canonical "Connect a provider" section in 4-AI-PROVIDERS with the real UI
  labels (Add Configuration, Test, Models/Discover Models, Add, Auto-assign
  Defaults) and a final test chat; every install path links to it.
- Docker settings go in the open_notebook environment block and are applied
  with `docker compose up -d`; .env only fills ${...} placeholders.
- Fix single-container /mydata volume and root:root requirement, external
  Ollama on Linux (extra_hosts + OLLAMA_HOST=0.0.0.0), from-source SURREAL_URL,
  prerequisites (Python 3.11-3.12, Node 20.9+, ffmpeg), wrong service names,
  down -v, backups and updates.
- Provider table regenerated from provider_registry.py (24 providers, with
  modalities); retired models and prices removed.
- Merge the OpenAI quick start into the cloud one (pointer left behind).
- README: license badge, provider matrix, languages, roadmap -> VISION.md.
- docs/index.md reduced to one navigation table, version stamp removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: address review (network exposure, key generation, Ollama reachability, migration)

- Warn before the first `docker compose up -d` that 8502/5055 are published on
  all interfaces with no password; offer 127.0.0.1 binding or
  OPEN_NOTEBOOK_PASSWORD. Narrow the local quick start's privacy claim.
- No literal encryption keys: placeholders plus generate commands
  (openssl, PowerShell, `uv run python -c secrets`).
- Host Ollama: Docker Desktop usually works as is, with an OLLAMA_HOST
  fallback for macOS/Windows; stronger exposure caveat for 0.0.0.0.
- Single container: copy /mydata out of the container before removing it.
- Vertex AI form fields; local providers need no key; Add Source menu wording.
- from-source: SURREAL_URL=127.0.0.1, INTERNAL_API_URL when the API port
  changes, mention `make start-all` (fixed on main).
- Windows: quote rocksdb paths. README: Italian, key optional for local.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: launchctl setenv is not persistent; restart Ollama after setting OLLAMA_HOST

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

2026-10-04 23:07:08 -03:00

2.9 KiB

Raw Permalink Blame History

Installation Guide

Pick the route that fits your setup. All of them end the same way: open the UI and connect a provider.

Route	For	You need
Docker Compose (recommended)	Almost everyone: laptops, home servers, VPS	Docker with Compose v2
From Source	Developers and contributors	Python 3.11–3.12, uv, Node.js 20.9+, Docker (for the database), ffmpeg
Windows Native	Windows machines that can't run Docker or WSL (for example ARM64)	Python 3.11–3.12 via uv, Node.js 20.9+, SurrealDB 2.x, ffmpeg
Single Container (deprecated)	Hosting platforms that run one container per app; removed in v2	Docker or a container host with persistent storage

Want a guided first run with a specific provider? The quick starts wrap the Docker Compose route with provider-specific steps (cloud API key, Ollama in Docker, Ollama on the host).

System requirements

RAM: 4 GB free at minimum, 8 GB or more recommended. Local models need much more (see Ollama).
Disk: room for the Docker images, your documents and any local models.
GPU: optional. It only matters for local models.
Network: needed to pull images and to reach cloud AI providers. With local models, Open Notebook works offline once installed.

AI providers

You need at least one provider for chat, and an embedding model for search. You configure them in the UI after installing, not in config files.

Cloud providers (OpenAI, Anthropic, Google, Mistral, OpenRouter and many more): pay per use; your content is sent to the provider.
Local providers (Ollama, oMLX, LM Studio, or another OpenAI-compatible server running on your own hardware): free to run; content stays on your hardware; speed depends on your hardware. An OpenAI-compatible endpoint hosted elsewhere is a cloud provider for privacy purposes.

The full list, with which providers cover chat, embeddings and speech, is in AI Providers.

After installing

Connect a provider and set the default models. Chat doesn't work until you do.
Create a notebook and add sources: User Guide.

Before exposing it to a network

The defaults are for a single user on a trusted machine: authentication is off and CORS is open.

Set OPEN_NOTEBOOK_PASSWORD: Security
Put it behind HTTPS: Reverse Proxy
Make sure the browser can reach the API: Access from another machine

2.9 KiB Raw Permalink Blame History Unescape Escape