diff --git a/.env.example b/.env.example index 8ff39a2..0821ea4 100644 --- a/.env.example +++ b/.env.example @@ -1,3 +1,13 @@ +# Conversion engine: "local" (in-process Docling) or "remote" (Docling Serve) +# CONVERSION_ENGINE=local + +# Docling Serve settings (remote mode only) +# DOCLING_SERVE_URL=http://localhost:5001 +# DOCLING_SERVE_API_KEY= + +# Max seconds per conversion (default: 600) +# CONVERSION_TIMEOUT=600 + # CORS (comma-separated origins, only needed for custom deployments) # CORS_ORIGINS=http://localhost:3000,https://your-domain.com diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bea8895..50b4605 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,7 +22,13 @@ Thank you for your interest in contributing to Docling Studio! This guide will h ```bash cd document-parser python -m venv .venv && source .venv/bin/activate + +# Remote mode (lightweight — delegates to Docling Serve) pip install -r requirements.txt + +# Local mode (full — runs Docling in-process) +pip install -r requirements-local.txt + pip install ruff pytest pytest-asyncio httpx # dev tools uvicorn main:app --reload --port 8000 ``` @@ -129,11 +135,16 @@ We use [Semantic Versioning](https://semver.org/): `MAJOR.MINOR.PATCH`. ### Docker Image Tags +Each release produces two image variants: + | Tag | Description | |-----|-------------| -| `X.Y.Z` | Exact version | -| `X.Y` | Latest patch of this minor | -| `latest` | Latest stable release | +| `X.Y.Z-remote` | Exact version — lightweight (Docling Serve) | +| `X.Y.Z-local` | Exact version — full (in-process Docling) | +| `X.Y-remote` | Latest patch of this minor — lightweight | +| `X.Y-local` | Latest patch of this minor — full | +| `latest-remote` | Latest stable — lightweight | +| `latest-local` | Latest stable — full | ### Hotfix diff --git a/README.md b/README.md index 5ac1323..0a70625 100644 --- a/README.md +++ b/README.md @@ -85,22 +85,42 @@ frontend/src/ ## Quick Start -### Docker (fastest) +Docling Studio ships two Docker image variants: + +| Variant | Image tag | Size | Description | +|---------|-----------|------|-------------| +| **remote** | `latest-remote` | ~300 MB | Lightweight — delegates to an external [Docling Serve](https://github.com/DS4SD/docling-serve) instance | +| **local** | `latest-local` | ~2–3 GB | Full — runs Docling in-process (downloads ML models on first run) | + +### Docker — remote mode (fastest) ```bash -docker run -p 3000:3000 ghcr.io/scub-france/docling-studio:latest +docker run -p 3000:3000 \ + -e DOCLING_SERVE_URL=http://your-docling-serve:5001 \ + ghcr.io/scub-france/docling-studio:latest-remote ``` -Open [http://localhost:3000](http://localhost:3000) +### Docker — local mode (self-contained) + +```bash +docker run -p 3000:3000 ghcr.io/scub-france/docling-studio:latest-local +``` > **Note:** The first analysis takes longer as Docling downloads its ML models (~400 MB). Subsequent runs are fast. +Open [http://localhost:3000](http://localhost:3000) + ### Docker Compose (for development) ```bash git clone https://github.com/scub-france/Docling-Studio.git cd Docling-Studio + +# Local mode (default) docker compose up --build + +# Remote mode +CONVERSION_MODE=remote DOCLING_SERVE_URL=http://your-docling-serve:5001 docker compose up --build ``` ### Local Development @@ -109,7 +129,13 @@ docker compose up --build ```bash cd document-parser python -m venv .venv && source .venv/bin/activate + +# Remote mode (lightweight) pip install -r requirements.txt + +# Local mode (with Docling) +pip install -r requirements-local.txt + uvicorn main:app --reload --port 8000 ``` @@ -156,6 +182,9 @@ All configuration is done via environment variables. See [`.env.example`](.env.e | Variable | Default | Description | |----------|---------|-------------| +| `CONVERSION_ENGINE` | `local` | `local` (in-process Docling) or `remote` (Docling Serve) | +| `DOCLING_SERVE_URL` | `http://localhost:5001` | Docling Serve endpoint (remote mode only) | +| `DOCLING_SERVE_API_KEY` | — | API key for Docling Serve (optional) | | `CORS_ORIGINS` | `http://localhost:3000,...` | CORS allowed origins (comma-separated) | | `UPLOAD_DIR` | `./uploads` | File storage directory | | `DB_PATH` | `./data/docling_studio.db` | SQLite database path | @@ -168,7 +197,7 @@ GitHub Actions pipelines (see [`.github/workflows/`](.github/workflows/)): | Workflow | Trigger | What it does | |----------|---------|--------------| | **CI** | push to `main`, pull requests | Lint + type check + Backend tests + Frontend tests + build | -| **Release** | push tag `v*` | Build & push multi-arch Docker image to `ghcr.io` | +| **Release** | push tag `v*` | Build & push **two** multi-arch Docker images (`remote` + `local`) to `ghcr.io` | | **Docs** | push to `main` (docs changes) | Build & deploy MkDocs to GitHub Pages | We follow [Semantic Versioning](https://semver.org/) with a simplified Git Flow. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full release process. @@ -183,12 +212,11 @@ We follow [Semantic Versioning](https://semver.org/) with a simplified Git Flow. ### Docker Desktop settings -The document parser needs **at least 4 GB of RAM**: - -| Resource | Minimum | Recommended | -|----------|---------|-------------| -| Memory | 6 GB | 8 GB+ | -| CPUs | 4 | 8+ | +| | Remote image | Local image | +|---|---|---| +| **Image size** | ~300 MB | ~2–3 GB | +| **Memory** | 2 GB | 6 GB (recommended 8 GB+) | +| **CPUs** | 2 | 4 (recommended 8+) | ### Platform support diff --git a/docs/contributing.md b/docs/contributing.md index 17c6e7d..44412e3 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -20,7 +20,13 @@ ```bash cd document-parser python -m venv .venv && source .venv/bin/activate + + # Remote mode (lightweight — delegates to Docling Serve) pip install -r requirements.txt + + # Local mode (full — runs Docling in-process) + pip install -r requirements-local.txt + pip install ruff pytest pytest-asyncio httpx uvicorn main:app --reload --port 8000 ``` diff --git a/docs/getting-started.md b/docs/getting-started.md index cd38397..8e8bbcf 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,33 +1,67 @@ # Getting Started -## Docker Compose (recommended) +Docling Studio ships two Docker image variants: + +| Variant | Image tag | Size | Description | +|---------|-----------|------|-------------| +| **remote** | `latest-remote` | ~300 MB | Lightweight — delegates to an external [Docling Serve](https://github.com/DS4SD/docling-serve) instance | +| **local** | `latest-local` | ~2–3 GB | Full — runs Docling in-process (downloads ML models on first run) | + +## Docker — remote mode (fastest) + +```bash +docker run -p 3000:3000 \ + -e DOCLING_SERVE_URL=http://your-docling-serve:5001 \ + ghcr.io/scub-france/docling-studio:latest-remote +``` + +## Docker — local mode (self-contained) + +```bash +docker run -p 3000:3000 ghcr.io/scub-france/docling-studio:latest-local +``` + +> **Note:** The first analysis takes longer as Docling downloads its ML models (~400 MB). Subsequent runs are fast. + +Open [http://localhost:3000](http://localhost:3000). + +## Docker Compose (recommended for development) ```bash git clone https://github.com/scub-france/Docling-Studio.git cd Docling-Studio -docker compose up --build -``` -Open [http://localhost:3000](http://localhost:3000). +# Local mode (default) +docker compose up --build + +# Remote mode +CONVERSION_MODE=remote DOCLING_SERVE_URL=http://your-docling-serve:5001 docker compose up --build +``` ## Local Development -### Backend (Python 3.12+) +=== "Backend (Python 3.12+)" -```bash -cd document-parser -python -m venv .venv && source .venv/bin/activate -pip install -r requirements.txt -uvicorn main:app --reload --port 8000 -``` + ```bash + cd document-parser + python -m venv .venv && source .venv/bin/activate -### Frontend (Node 20+) + # Remote mode (lightweight) + pip install -r requirements.txt -```bash -cd frontend -npm install -npm run dev -``` + # Local mode (with Docling) + pip install -r requirements-local.txt + + uvicorn main:app --reload --port 8000 + ``` + +=== "Frontend (Node 20+)" + + ```bash + cd frontend + npm install + npm run dev + ``` The frontend runs on `http://localhost:3000` and proxies API calls to `http://localhost:8000`. @@ -71,6 +105,9 @@ All configuration is done via environment variables: | Variable | Default | Description | |----------|---------|-------------| +| `CONVERSION_ENGINE` | `local` | `local` (in-process Docling) or `remote` (Docling Serve) | +| `DOCLING_SERVE_URL` | `http://localhost:5001` | Docling Serve endpoint (remote mode only) | +| `DOCLING_SERVE_API_KEY` | — | API key for Docling Serve (optional) | | `CORS_ORIGINS` | `http://localhost:3000,...` | CORS allowed origins | | `UPLOAD_DIR` | `./uploads` | File storage directory | | `DB_PATH` | `./data/docling_studio.db` | SQLite database path | @@ -78,9 +115,10 @@ All configuration is done via environment variables: ## System Requirements -| Resource | Minimum | Recommended | -|----------|---------|-------------| -| Memory | 6 GB | 8 GB+ | -| CPUs | 4 | 8+ | +| | Remote image | Local image | +|---|---|---| +| **Image size** | ~300 MB | ~2–3 GB | +| **Memory** | 2 GB | 6 GB (recommended 8 GB+) | +| **CPUs** | 2 | 4 (recommended 8+) | All Docker images are multi-arch (`linux/amd64` + `linux/arm64`). No GPU required.