OpenNotebook API (FastAPI): grounded RAG chat, knowledge graph, multi-provider model gateway
419
Self-hosted knowledge workspace with grounded RAG chat and traceable citations. Upload documents, source code, archives, images, web pages and notes; organize them in a freely nested Project → Workspace → Notebook tree; chat with an LLM that answers only from the sources in the selected scope, with every statement linked to the exact passage it comes from.
This image runs the API (FastAPI): authentication, the project/workspace/notebook hierarchy and permissions,
the provider registry and model gateway (LiteLLM), uploads, hybrid search, the grounded chat stream, the
knowledge graph and wiki pages. The same image runs the one-shot migrate job (database migrations and
first-start initialization).
This image is one of the three OpenNotebook application images. Run them together with the Compose file described below — they are not meant to be started alone.
| Image | Role |
|---|---|
lordraw/opennotebook-web | Web UI (Angular) on unprivileged nginx; proxies /api to the api |
lordraw/opennotebook-api | REST + streaming API (FastAPI); also runs the one-shot migrate job |
lordraw/opennotebook-worker | Ingestion worker (Celery): parsing, OCR, web fetching, embeddings, knowledge graph, summaries |
lordraw/opennotebook-converter | Optional isolated document converter (headless LibreOffice): office files to PDF |
lordraw/opennotebook-renderer | Optional isolated page renderer (headless Chromium): web pages that need JavaScript |
The images contain no model weights, no inference server and no ML runtime. Every model call (chat, summaries, knowledge-graph extraction, image description, OCR, embeddings, rerank) goes to an external provider you configure: Groq, OpenRouter, Google Gemini, Cloudflare Workers AI, Cerebras, Mistral, NVIDIA NIM, Hugging Face, or your own Ollama server. Each phase has its own model chain with fallbacks, globally or per project. A working instance needs one chat model and one embedding model (Gemini or Mistral alone covers both).
[S1] citations that open the source at the
cited passage (PDF page with the passage highlighted, or the text / code lines), provider fallback, save an answer
as a note; an optional second model checks that the cited passages support the answer.Requirements: Docker Engine with the Compose plugin (v2.23+), 4 GB RAM (8 GB recommended), outbound HTTPS to your model providers.
mkdir opennotebook && cd opennotebook
BASE=https://raw.githubusercontent.com/lordraw77/OpenNotebook/HEAD
curl -fsSLO $BASE/deploy/production/docker-compose.yml
curl -fsSLO $BASE/.env.example
curl -fsSL $BASE/scripts/gen-secrets.sh -o gen-secrets.sh && chmod +x gen-secrets.sh
./gen-secrets.sh .env # creates .env and generates every internal secret + the first admin password
$EDITOR .env # BOOTSTRAP_ADMIN_EMAIL, at least one provider key, optional MODEL_* defaults
docker compose up -d
Open http://<host>:8080 and sign in with BOOTSTRAP_ADMIN_EMAIL and the generated
BOOTSTRAP_ADMIN_PASSWORD (in .env). Then: Settings → Providers (check providers and models),
Settings → Models (chains per phase), Workbench (create a project, upload sources, ask).
The Compose file starts the three OpenNotebook images plus PostgreSQL 18, Qdrant, SeaweedFS (S3 storage) and
Redis. Optional profiles: observability (Prometheus, Grafana, Jaeger), auth (Keycloak), converter
(office documents to PDF, with CONVERTER_URL=http://converter:8080) and renderer (JavaScript pages, with
RENDERER_URL=http://renderer:8080):
docker compose --profile observability up -d.
| Tag | Content |
|---|---|
1.4.3 | Visio drawings (.vsdx read from the file: shapes and the connections between them; .vsd and PDF preview through the converter), visible "New chat" button |
1.4.2 | Processes page with telemetry and running files, WORKER_CONCURRENCY, quieter model-call logs, NAT helper script, updated in-app guide with new screenshots |
1.4.1 | Stop all and reset all for ingestion, per-file and overall completion on the Sources page, what is being worked on in RAG Status |
1.4.0 | JavaScript page renderer (optional image), Sources page, topics and duplicate suggestions in the graph, draggable graph, compressed single files, SSO logout and group re-sync, per-model provider policy, optional groundedness judge |
1.3.0 | 7z and RAR archives, pictures inside PDF/DOCX read by models, OCR text anchored to line boxes, in-app user guide |
1.2.0 | Iterative deep research, model-rewritten follow-ups, no double embedding on model change, chat history |
1.1.0 | Git repository sources with scheduled sync, native XLSX/PPTX import, editable knowledge graph |
1.0.1 | Rerank through Ollama-compatible proxies (llmproxy) |
1.0.0 | First stable release: observability, operations, isolated office converter, lazy source tree, Italian UI, Helm chart |
0.5.1 | Fix: sources can be uploaded to projects and workspaces, not only notebooks |
0.5.0 | M0–M5: adds groups, single sign-on (OIDC), provider policy per project, zero-downtime embedding change, deep research mode |
0.4.0 | M0–M4: foundations, ingestion, grounded chat, extended ingestion, knowledge graph and wiki |
latest | The most recent release |
Pin an exact version in production (VERSION=1.4.3 in .env). The three images of a deployment must have the
same version. Images are linux/amd64.
opennotebook; commands: api (default, port 8000), migrate, bootstrap, worker.uv.lock; LiteLLM pinned to an exact
version.GET /api/health/live (process) and GET /api/health/ready (PostgreSQL, Redis, Qdrant,
storage); Prometheus metrics on /metrics (internal network only)..env — see .env.example in the repository for every setting
(database, Qdrant, Redis, S3 storage, provider keys, MODEL_* defaults, chat, ingestion and graph limits).no-new-privileges and drops all
capabilities.APP_ENCRYPTION_KEY — back that key up together with
the pg-data volume.Volumes: pg-data (source of truth), blob-data (original files), qdrant-data (vector index, rebuildable by
re-indexing), redis-data (queues). Back up pg-data, blob-data and APP_ENCRYPTION_KEY.
Set the new VERSION in .env, then docker compose pull && docker compose up -d. Database migrations run
automatically in the migrate job before the api and worker start.
docs/deploy.md · Docker overview (services, profiles, volumes, troubleshooting):
docs/docker.md · Architecture and threat model: docs/analysis/Content type
Image
Digest
sha256:558d4922e…
Size
243.7 MB
Last updated
9 days ago
docker pull lordraw/opennotebook-api