danvics/docling-studio
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

Update documentation for remote/local image variants

Browse source 
Reflect the two Docker targets across README, getting-started,
contributing guides, and .env.example with new configuration
variables (CONVERSION_ENGINE, DOCLING_SERVE_URL, DOCLING_SERVE_API_KEY).
This commit is contained in:
Pier-Jean Malandrino 2026-04-02 21:47:34 +02:00
parent 3dd7470562
commit aa7c539cc3
5 changed files with 127 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
.env.example
View file

@ -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 (comma-separated origins, only needed for custom deployments)
# CORS_ORIGINS=http://localhost:3000,https://your-domain.com # CORS_ORIGINS=http://localhost:3000,https://your-domain.com

17
CONTRIBUTING.md
View file

@ -22,7 +22,13 @@ Thank you for your interest in contributing to Docling Studio! This guide will h
```bash ```bash
cd document-parser cd document-parser
python -m venv .venv && source .venv/bin/activate python -m venv .venv && source .venv/bin/activate
# Remote mode (lightweight — delegates to Docling Serve)
pip install -r requirements.txt 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 pip install ruff pytest pytest-asyncio httpx # dev tools
uvicorn main:app --reload --port 8000 uvicorn main:app --reload --port 8000
``` ```
@ -129,11 +135,16 @@ We use [Semantic Versioning](https://semver.org/): `MAJOR.MINOR.PATCH`.
### Docker Image Tags ### Docker Image Tags
Each release produces two image variants:
| Tag | Description | | Tag | Description |
|-----|-------------| |-----|-------------|
| `X.Y.Z` | Exact version | | `X.Y.Z-remote` | Exact version — lightweight (Docling Serve) |
| `X.Y` | Latest patch of this minor | | `X.Y.Z-local` | Exact version — full (in-process Docling) |
| `latest` | Latest stable release | | `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 ### Hotfix

48
README.md
View file

@ -85,22 +85,42 @@ frontend/src/
## Quick Start ## 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 ```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. > **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) ### Docker Compose (for development)
```bash ```bash
git clone https://github.com/scub-france/Docling-Studio.git git clone https://github.com/scub-france/Docling-Studio.git
cd Docling-Studio cd Docling-Studio
# Local mode (default)
docker compose up --build docker compose up --build
# Remote mode
CONVERSION_MODE=remote DOCLING_SERVE_URL=http://your-docling-serve:5001 docker compose up --build
``` ```
### Local Development ### Local Development
@ -109,7 +129,13 @@ docker compose up --build
```bash ```bash
cd document-parser cd document-parser
python -m venv .venv && source .venv/bin/activate python -m venv .venv && source .venv/bin/activate
# Remote mode (lightweight)
pip install -r requirements.txt pip install -r requirements.txt
# Local mode (with Docling)
pip install -r requirements-local.txt
uvicorn main:app --reload --port 8000 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 | | 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) | | `CORS_ORIGINS` | `http://localhost:3000,...` | CORS allowed origins (comma-separated) |
| `UPLOAD_DIR` | `./uploads` | File storage directory | | `UPLOAD_DIR` | `./uploads` | File storage directory |
| `DB_PATH` | `./data/docling_studio.db` | SQLite database path | | `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 | | Workflow | Trigger | What it does |
|----------|---------|--------------| |----------|---------|--------------|
| **CI** | push to `main`, pull requests | Lint + type check + Backend tests + Frontend tests + build | | **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 | | **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. 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 ### Docker Desktop settings
The document parser needs **at least 4 GB of RAM**: | | Remote image | Local image |
|---|---|---|
| Resource | Minimum | Recommended | | **Image size** | ~300 MB | ~2–3 GB |
|----------|---------|-------------| | **Memory** | 2 GB | 6 GB (recommended 8 GB+) |
| Memory | 6 GB | 8 GB+ | | **CPUs** | 2 | 4 (recommended 8+) |
| CPUs | 4 | 8+ |
### Platform support ### Platform support

6
docs/contributing.md
View file

@ -20,7 +20,13 @@
```bash ```bash
cd document-parser cd document-parser
python -m venv .venv && source .venv/bin/activate python -m venv .venv && source .venv/bin/activate
# Remote mode (lightweight — delegates to Docling Serve)
pip install -r requirements.txt 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 pip install ruff pytest pytest-asyncio httpx
uvicorn main:app --reload --port 8000 uvicorn main:app --reload --port 8000
``` ```

80
docs/getting-started.md
View file

@ -1,33 +1,67 @@
# Getting Started # 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 ```bash
git clone https://github.com/scub-france/Docling-Studio.git git clone https://github.com/scub-france/Docling-Studio.git
cd Docling-Studio 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 ## Local Development
### Backend (Python 3.12+) === "Backend (Python 3.12+)"
```bash ```bash
cd document-parser cd document-parser
python -m venv .venv && source .venv/bin/activate python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --reload --port 8000
```
### Frontend (Node 20+) # Remote mode (lightweight)
pip install -r requirements.txt
```bash # Local mode (with Docling)
cd frontend pip install -r requirements-local.txt
npm install
npm run dev 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`. 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 | | 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 | | `CORS_ORIGINS` | `http://localhost:3000,...` | CORS allowed origins |
| `UPLOAD_DIR` | `./uploads` | File storage directory | | `UPLOAD_DIR` | `./uploads` | File storage directory |
| `DB_PATH` | `./data/docling_studio.db` | SQLite database path | | `DB_PATH` | `./data/docling_studio.db` | SQLite database path |
@ -78,9 +115,10 @@ All configuration is done via environment variables:
## System Requirements ## System Requirements
| Resource | Minimum | Recommended | | | Remote image | Local image |
|----------|---------|-------------| |---|---|---|
| Memory | 6 GB | 8 GB+ | | **Image size** | ~300 MB | ~2–3 GB |
| CPUs | 4 | 8+ | | **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. All Docker images are multi-arch (`linux/amd64` + `linux/arm64`). No GPU required.