chore: bump version to 1.3.0 [skip ci]

Signed-off-by: Viktor Kuropiatnyk <vku@zurich.ibm.com>
Signed-off-by: Michele Dolfi <dol@zurich.ibm.com>
Co-authored-by: Michele Dolfi <dol@zurich.ibm.com>

.github/styles/config/vocabularies/Docling/accept.txt

@@ -5,6 +5,8 @@ async
 (?i)urls
 uvicorn
 [Ww]ebserver
+RQ
+(?i)url
 keyfile
 [Ww]ebsocket(s?)
 [Kk]ubernetes
@@ -22,6 +24,7 @@ Kubeflow
 (?i)ROCm
 (?i)env
 Gradio
+Podman
 bool
 Ollama
 inbody

CHANGELOG.md

@@ -1,3 +1,22 @@
+## [v1.3.0](https://github.com/docling-project/docling-serve/releases/tag/v1.3.0) - 2025-08-14
+
+### Feature
+
+* Add configuration option for apikey security ([#322](https://github.com/docling-project/docling-serve/issues/322)) ([`9a64410`](https://github.com/docling-project/docling-serve/commit/9a644105523d312431993ded8dd88e064550a5db))
+* Add RQ engine ([#315](https://github.com/docling-project/docling-serve/issues/315)) ([`885f319`](https://github.com/docling-project/docling-serve/commit/885f319d3a3488a4090869560447437a4104f14e))
+
+### Documentation
+
+* Example of docling-serve deployment in the RQ engine mode ([#321](https://github.com/docling-project/docling-serve/issues/321)) ([`71edf41`](https://github.com/docling-project/docling-serve/commit/71edf4184960d8664ef9da20617e2d0f91793d36))
+* Handling models in docling-serve ([#319](https://github.com/docling-project/docling-serve/issues/319)) ([`6e9aa8c`](https://github.com/docling-project/docling-serve/commit/6e9aa8c759220458281c7fe4c87443ac41023eee))
+* Add Gradio cache usage ([#312](https://github.com/docling-project/docling-serve/issues/312)) ([`d584895`](https://github.com/docling-project/docling-serve/commit/d584895e1108d71a0f45deadcd3c669eb0a58133))
+
+## [v1.2.2](https://github.com/docling-project/docling-serve/releases/tag/v1.2.2) - 2025-08-13
+
+### Fix
+
+* Update of transformers module to 4.55.1 ([#316](https://github.com/docling-project/docling-serve/issues/316)) ([`7692eb2`](https://github.com/docling-project/docling-serve/commit/7692eb26006fd4deaa021180c99e23a1b65de506))
+
 ## [v1.2.1](https://github.com/docling-project/docling-serve/releases/tag/v1.2.1) - 2025-08-13
 
 ### Fix

docling_serve/__main__.py

@@ -11,6 +11,7 @@ import uvicorn
 from rich.console import Console
 
 from docling_serve.settings import docling_serve_settings, uvicorn_settings
+from docling_serve.storage import get_scratch
 
 warnings.filterwarnings(action="ignore", category=UserWarning, module="pydantic|torch")
 warnings.filterwarnings(action="ignore", category=FutureWarning, module="easyocr")
@@ -361,6 +362,37 @@ def run(
     )
 
 
+@app.command()
+def rq_worker() -> Any:
+    """
+    Run the [bold]Docling JobKit[/bold] RQ worker.
+    """
+    from docling_jobkit.convert.manager import DoclingConverterManagerConfig
+    from docling_jobkit.orchestrators.rq.orchestrator import RQOrchestratorConfig
+    from docling_jobkit.orchestrators.rq.worker import run_worker
+
+    rq_config = RQOrchestratorConfig(
+        redis_url=docling_serve_settings.eng_rq_redis_url,
+        results_prefix=docling_serve_settings.eng_rq_results_prefix,
+        sub_channel=docling_serve_settings.eng_rq_sub_channel,
+        scratch_dir=get_scratch(),
+    )
+
+    cm_config = DoclingConverterManagerConfig(
+        artifacts_path=docling_serve_settings.artifacts_path,
+        options_cache_size=docling_serve_settings.options_cache_size,
+        enable_remote_services=docling_serve_settings.enable_remote_services,
+        allow_external_plugins=docling_serve_settings.allow_external_plugins,
+        max_num_pages=docling_serve_settings.max_num_pages,
+        max_file_size=docling_serve_settings.max_file_size,
+    )
+
+    run_worker(
+        rq_config=rq_config,
+        cm_config=cm_config,
+    )
+
+
 def main() -> None:
     app()
 

docling_serve/app.py

@@ -18,6 +18,7 @@ from fastapi import (
     UploadFile,
     WebSocket,
     WebSocketDisconnect,
+    status,
 )
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.openapi.docs import (
@@ -48,6 +49,7 @@ from docling_jobkit.orchestrators.base_orchestrator import (
     TaskNotFoundError,
 )
 
+from docling_serve.auth import APIKeyAuth, AuthenticationResult
 from docling_serve.datamodel.convert import ConvertDocumentsRequestOptions
 from docling_serve.datamodel.requests import (
     ConvertDocumentsRequest,
@@ -156,6 +158,7 @@ def create_app():  # noqa: C901
         offline_docs_assets = True
         _log.info("Found static assets.")
 
+    require_auth = APIKeyAuth(docling_serve_settings.api_key)
     app = FastAPI(
         title="Docling Serve",
         docs_url=None if offline_docs_assets else "/swagger",
@@ -400,6 +403,7 @@ def create_app():  # noqa: C901
     )
     async def process_url(
         background_tasks: BackgroundTasks,
+        auth: Annotated[AuthenticationResult, Depends(require_auth)],
         orchestrator: Annotated[BaseOrchestrator, Depends(get_async_orchestrator)],
         conversion_request: ConvertDocumentsRequest,
     ):
@@ -417,9 +421,17 @@ def create_app():  # noqa: C901
                 detail=f"Conversion is taking too long. The maximum wait time is configure as DOCLING_SERVE_MAX_SYNC_WAIT={docling_serve_settings.max_sync_wait}.",
             )
 
-        task = await orchestrator.get_raw_task(task_id=task.task_id)
+        task_result = await orchestrator.task_result(task_id=task.task_id)
+        if task_result is None:
+            raise HTTPException(
+                status_code=404,
+                detail="Task result not found. Please wait for a completion status.",
+            )
         response = await prepare_response(
-            task=task, orchestrator=orchestrator, background_tasks=background_tasks
+            task_id=task.task_id,
+            task_result=task_result,
+            orchestrator=orchestrator,
+            background_tasks=background_tasks,
         )
         return response
 
@@ -435,6 +447,7 @@ def create_app():  # noqa: C901
     )
     async def process_file(
         background_tasks: BackgroundTasks,
+        auth: Annotated[AuthenticationResult, Depends(require_auth)],
         orchestrator: Annotated[BaseOrchestrator, Depends(get_async_orchestrator)],
         files: list[UploadFile],
         options: Annotated[
@@ -457,9 +470,17 @@ def create_app():  # noqa: C901
                 detail=f"Conversion is taking too long. The maximum wait time is configure as DOCLING_SERVE_MAX_SYNC_WAIT={docling_serve_settings.max_sync_wait}.",
             )
 
-        task = await orchestrator.get_raw_task(task_id=task.task_id)
+        task_result = await orchestrator.task_result(task_id=task.task_id)
+        if task_result is None:
+            raise HTTPException(
+                status_code=404,
+                detail="Task result not found. Please wait for a completion status.",
+            )
         response = await prepare_response(
-            task=task, orchestrator=orchestrator, background_tasks=background_tasks
+            task_id=task.task_id,
+            task_result=task_result,
+            orchestrator=orchestrator,
+            background_tasks=background_tasks,
         )
         return response
 
@@ -469,6 +490,7 @@ def create_app():  # noqa: C901
         response_model=TaskStatusResponse,
     )
     async def process_url_async(
+        auth: Annotated[AuthenticationResult, Depends(require_auth)],
         orchestrator: Annotated[BaseOrchestrator, Depends(get_async_orchestrator)],
         conversion_request: ConvertDocumentsRequest,
     ):
@@ -491,6 +513,7 @@ def create_app():  # noqa: C901
         response_model=TaskStatusResponse,
     )
     async def process_file_async(
+        auth: Annotated[AuthenticationResult, Depends(require_auth)],
         orchestrator: Annotated[BaseOrchestrator, Depends(get_async_orchestrator)],
         background_tasks: BackgroundTasks,
         files: list[UploadFile],
@@ -519,6 +542,7 @@ def create_app():  # noqa: C901
         response_model=TaskStatusResponse,
     )
     async def task_status_poll(
+        auth: Annotated[AuthenticationResult, Depends(require_auth)],
         orchestrator: Annotated[BaseOrchestrator, Depends(get_async_orchestrator)],
         task_id: str,
         wait: Annotated[
@@ -546,7 +570,15 @@ def create_app():  # noqa: C901
         websocket: WebSocket,
         orchestrator: Annotated[BaseOrchestrator, Depends(get_async_orchestrator)],
         task_id: str,
+        api_key: Annotated[str, Query()] = "",
     ):
+        if docling_serve_settings.api_key:
+            if api_key != docling_serve_settings.api_key:
+                raise HTTPException(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    detail="Api key is required as ?api_key=SECRET.",
+                )
+
         assert isinstance(orchestrator.notifier, WebsocketNotifier)
         await websocket.accept()
 
@@ -613,14 +645,23 @@ def create_app():  # noqa: C901
         },
     )
     async def task_result(
+        auth: Annotated[AuthenticationResult, Depends(require_auth)],
         orchestrator: Annotated[BaseOrchestrator, Depends(get_async_orchestrator)],
         background_tasks: BackgroundTasks,
         task_id: str,
     ):
         try:
-            task = await orchestrator.get_raw_task(task_id=task_id)
+            task_result = await orchestrator.task_result(task_id=task_id)
+            if task_result is None:
+                raise HTTPException(
+                    status_code=404,
+                    detail="Task result not found. Please wait for a completion status.",
+                )
             response = await prepare_response(
-                task=task, orchestrator=orchestrator, background_tasks=background_tasks
+                task_id=task_id,
+                task_result=task_result,
+                orchestrator=orchestrator,
+                background_tasks=background_tasks,
             )
             return response
         except TaskNotFoundError:
@@ -632,6 +673,7 @@ def create_app():  # noqa: C901
         response_model=ProgressCallbackResponse,
     )
     async def callback_task_progress(
+        auth: Annotated[AuthenticationResult, Depends(require_auth)],
         orchestrator: Annotated[BaseOrchestrator, Depends(get_async_orchestrator)],
         request: ProgressCallbackRequest,
     ):
@@ -653,6 +695,7 @@ def create_app():  # noqa: C901
         response_model=ClearResponse,
     )
     async def clear_converters(
+        auth: Annotated[AuthenticationResult, Depends(require_auth)],
         orchestrator: Annotated[BaseOrchestrator, Depends(get_async_orchestrator)],
     ):
         await orchestrator.clear_converters()
@@ -664,6 +707,7 @@ def create_app():  # noqa: C901
         response_model=ClearResponse,
     )
     async def clear_results(
+        auth: Annotated[AuthenticationResult, Depends(require_auth)],
         orchestrator: Annotated[BaseOrchestrator, Depends(get_async_orchestrator)],
         older_then: float = 3600,
     ):

docling_serve/auth.py

@@ -0,0 +1,56 @@
+from typing import Any
+
+from fastapi import HTTPException, Request, status
+from fastapi.security import APIKeyHeader
+from pydantic import BaseModel
+
+
+class AuthenticationResult(BaseModel):
+    valid: bool
+    errors: list[str] = []
+    detail: Any | None = None
+
+
+class APIKeyAuth(APIKeyHeader):
+    """
+    FastAPI dependency which evaluates a status API Key.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        header_name: str = "X-Api-Key",
+        fail_on_unauthorized: bool = True,
+    ) -> None:
+        self.api_key = api_key
+        self.header_name = header_name
+        super().__init__(name=self.header_name, auto_error=False)
+
+    async def _validate_api_key(self, header_api_key: str | None):
+        if header_api_key is None:
+            return AuthenticationResult(
+                valid=False, errors=[f"Missing header {self.header_name}."]
+            )
+
+        header_api_key = header_api_key.strip()
+
+        # Otherwise check the apikey
+        if header_api_key == self.api_key or self.api_key == "":
+            return AuthenticationResult(
+                valid=True,
+                detail=header_api_key,
+            )
+        else:
+            return AuthenticationResult(
+                valid=False,
+                errors=["The provided API Key is invalid."],
+            )
+
+    async def __call__(self, request: Request) -> AuthenticationResult:  # type: ignore
+        header_api_key = await super().__call__(request=request)
+        result = await self._validate_api_key(header_api_key)
+        if self.api_key and not result.valid:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED, detail=result.detail
+            )
+        return result

docling_serve/datamodel/responses.py

@@ -5,7 +5,7 @@ from pydantic import BaseModel
 
 from docling.datamodel.document import ConversionStatus, ErrorItem
 from docling.utils.profiling import ProfilingItem
-from docling_core.types.doc import DoclingDocument
+from docling_jobkit.datamodel.result import ExportDocumentResponse
 from docling_jobkit.datamodel.task_meta import TaskProcessingMeta
 
 
@@ -18,17 +18,8 @@ class ClearResponse(BaseModel):
     status: str = "ok"
 
 
-class DocumentResponse(BaseModel):
-    filename: str
-    md_content: Optional[str] = None
-    json_content: Optional[DoclingDocument] = None
-    html_content: Optional[str] = None
-    text_content: Optional[str] = None
-    doctags_content: Optional[str] = None
-
-
 class ConvertDocumentResponse(BaseModel):
-    document: DocumentResponse
+    document: ExportDocumentResponse
     status: ConversionStatus
     errors: list[ErrorItem] = []
     processing_time: float
@@ -36,8 +27,10 @@ class ConvertDocumentResponse(BaseModel):
 
 
 class PresignedUrlConvertDocumentResponse(BaseModel):
-    status: ConversionStatus
     processing_time: float
+    num_converted: int
+    num_succeeded: int
+    num_failed: int
 
 
 class ConvertDocumentErrorResponse(BaseModel):

docling_serve/gradio_ui.py

@@ -233,15 +233,21 @@ def change_ocr_lang(ocr_engine):
         return "english,chinese"
 
 
-def wait_task_finish(task_id: str, return_as_file: bool):
+def wait_task_finish(auth: str, task_id: str, return_as_file: bool):
     conversion_sucess = False
     task_finished = False
     task_status = ""
+
+    headers = {}
+    if docling_serve_settings.api_key:
+        headers["X-Api-Key"] = str(auth)
+
     ssl_ctx = get_ssl_context()
     while not task_finished:
         try:
             response = httpx.get(
                 f"{get_api_endpoint()}/v1/status/poll/{task_id}?wait=5",
+                headers=headers,
                 verify=ssl_ctx,
                 timeout=15,
             )
@@ -265,6 +271,7 @@ def wait_task_finish(task_id: str, return_as_file: bool):
         try:
             response = httpx.get(
                 f"{get_api_endpoint()}/v1/result/{task_id}",
+                headers=headers,
                 timeout=15,
                 verify=ssl_ctx,
             )
@@ -279,6 +286,7 @@ def wait_task_finish(task_id: str, return_as_file: bool):
 
 
 def process_url(
+    auth,
     input_sources,
     to_formats,
     image_export_mode,
@@ -326,11 +334,18 @@ def process_url(
     ):
         logger.error("No input sources provided.")
         raise gr.Error("No input sources provided.", print_exception=False)
+
+    headers = {}
+    if docling_serve_settings.api_key:
+        headers["X-Api-Key"] = str(auth)
+
+    print(f"{headers=}")
     try:
         ssl_ctx = get_ssl_context()
         response = httpx.post(
             f"{get_api_endpoint()}/v1/convert/source/async",
             json=parameters,
+            headers=headers,
             verify=ssl_ctx,
             timeout=60,
         )
@@ -354,6 +369,7 @@ def file_to_base64(file):
 
 
 def process_file(
+    auth,
     files,
     to_formats,
     image_export_mode,
@@ -402,11 +418,16 @@ def process_file(
         "target": target,
     }
 
+    headers = {}
+    if docling_serve_settings.api_key:
+        headers["X-Api-Key"] = str(auth)
+
     try:
         ssl_ctx = get_ssl_context()
         response = httpx.post(
             f"{get_api_endpoint()}/v1/convert/source/async",
             json=parameters,
+            headers=headers,
             verify=ssl_ctx,
             timeout=60,
         )
@@ -480,7 +501,7 @@ with gr.Blocks(
     css=css,
     theme=theme,
     title="Docling Serve",
-    delete_cache=(3600, 3600),  # Delete all files older than 1 hour every hour
+    delete_cache=(3600, 36000),  # Delete all files older than 10 hour every hour
 ) as ui:
     # Constants stored in states to be able to pass them as inputs to functions
     processing_text = gr.State("Processing your document(s), please wait...")
@@ -565,6 +586,15 @@ with gr.Blocks(
                 file_process_btn = gr.Button("Process File", scale=1)
                 file_reset_btn = gr.Button("Reset", scale=1)
 
+    # Auth
+    with gr.Row(visible=bool(docling_serve_settings.api_key)):
+        with gr.Column():
+            auth = gr.Textbox(
+                label="Authentication",
+                placeholder="API Key",
+                type="password",
+            )
+
     # Options
     with gr.Accordion("Options") as options:
         with gr.Row():
@@ -590,6 +620,7 @@ with gr.Blocks(
                     label="Image Export Mode",
                     value="embedded",
                 )
+
         with gr.Row():
             with gr.Column(scale=1, min_width=200):
                 pipeline = gr.Radio(
@@ -724,6 +755,7 @@ with gr.Blocks(
     ).then(
         process_url,
         inputs=[
+            auth,
             url_input,
             to_formats,
             image_export_mode,
@@ -750,7 +782,7 @@ with gr.Blocks(
         outputs=[content_output, file_output],
     ).then(
         wait_task_finish,
-        inputs=[task_id_rendered, return_as_file],
+        inputs=[auth, task_id_rendered, return_as_file],
         outputs=[
             output_markdown,
             output_markdown_rendered,
@@ -811,6 +843,7 @@ with gr.Blocks(
     ).then(
         process_file,
         inputs=[
+            auth,
             file_input,
             to_formats,
             image_export_mode,
@@ -837,7 +870,7 @@ with gr.Blocks(
         outputs=[content_output, file_output],
     ).then(
         wait_task_finish,
-        inputs=[task_id_rendered, return_as_file],
+        inputs=[auth, task_id_rendered, return_as_file],
         outputs=[
             output_markdown,
             output_markdown_rendered,

docling_serve/orchestrator_factory.py

@@ -3,6 +3,7 @@ from functools import lru_cache
 from docling_jobkit.orchestrators.base_orchestrator import BaseOrchestrator
 
 from docling_serve.settings import AsyncEngine, docling_serve_settings
+from docling_serve.storage import get_scratch
 
 
 @lru_cache
@@ -20,6 +21,7 @@ def get_async_orchestrator() -> BaseOrchestrator:
         local_config = LocalOrchestratorConfig(
             num_workers=docling_serve_settings.eng_loc_num_workers,
             shared_models=docling_serve_settings.eng_loc_share_models,
+            scratch_dir=get_scratch(),
         )
 
         cm_config = DoclingConverterManagerConfig(
@@ -33,6 +35,20 @@ def get_async_orchestrator() -> BaseOrchestrator:
         cm = DoclingConverterManager(config=cm_config)
 
         return LocalOrchestrator(config=local_config, converter_manager=cm)
+    elif docling_serve_settings.eng_kind == AsyncEngine.RQ:
+        from docling_jobkit.orchestrators.rq.orchestrator import (
+            RQOrchestrator,
+            RQOrchestratorConfig,
+        )
+
+        rq_config = RQOrchestratorConfig(
+            redis_url=docling_serve_settings.eng_rq_redis_url,
+            results_prefix=docling_serve_settings.eng_rq_results_prefix,
+            sub_channel=docling_serve_settings.eng_rq_sub_channel,
+            scratch_dir=get_scratch(),
+        )
+
+        return RQOrchestrator(config=rq_config)
     elif docling_serve_settings.eng_kind == AsyncEngine.KFP:
         from docling_jobkit.orchestrators.kfp.orchestrator import (
             KfpOrchestrator,

docling_serve/response_preparation.py

@@ -1,317 +1,65 @@
 import asyncio
 import logging
-import os
-import shutil
-import time
-from collections.abc import Iterable
-from pathlib import Path
-from typing import Union
 
-import httpx
-from fastapi import BackgroundTasks, HTTPException
-from fastapi.responses import FileResponse
+from fastapi import BackgroundTasks, Response
 
-from docling.datamodel.base_models import OutputFormat
-from docling.datamodel.document import ConversionResult, ConversionStatus
-from docling_core.types.doc import ImageRefMode
-from docling_jobkit.datamodel.convert import ConvertDocumentsOptions
-from docling_jobkit.datamodel.task import Task
-from docling_jobkit.datamodel.task_targets import InBodyTarget, PutTarget, TaskTarget
+from docling_jobkit.datamodel.result import (
+    ConvertDocumentResult,
+    ExportResult,
+    RemoteTargetResult,
+    ZipArchiveResult,
+)
 from docling_jobkit.orchestrators.base_orchestrator import (
     BaseOrchestrator,
 )
 
 from docling_serve.datamodel.responses import (
     ConvertDocumentResponse,
-    DocumentResponse,
     PresignedUrlConvertDocumentResponse,
 )
 from docling_serve.settings import docling_serve_settings
-from docling_serve.storage import get_scratch
 
 _log = logging.getLogger(__name__)
 
 
-def _export_document_as_content(
-    conv_res: ConversionResult,
-    export_json: bool,
-    export_html: bool,
-    export_md: bool,
-    export_txt: bool,
-    export_doctags: bool,
-    image_mode: ImageRefMode,
-    md_page_break_placeholder: str,
-):
-    document = DocumentResponse(filename=conv_res.input.file.name)
-
-    if conv_res.status == ConversionStatus.SUCCESS:
-        new_doc = conv_res.document._make_copy_with_refmode(
-            Path(), image_mode, page_no=None
-        )
-
-        # Create the different formats
-        if export_json:
-            document.json_content = new_doc
-        if export_html:
-            document.html_content = new_doc.export_to_html(image_mode=image_mode)
-        if export_txt:
-            document.text_content = new_doc.export_to_markdown(
-                strict_text=True,
-                image_mode=image_mode,
-            )
-        if export_md:
-            document.md_content = new_doc.export_to_markdown(
-                image_mode=image_mode,
-                page_break_placeholder=md_page_break_placeholder or None,
-            )
-        if export_doctags:
-            document.doctags_content = new_doc.export_to_doctags()
-    elif conv_res.status == ConversionStatus.SKIPPED:
-        raise HTTPException(status_code=400, detail=conv_res.errors)
-    else:
-        raise HTTPException(status_code=500, detail=conv_res.errors)
-
-    return document
-
-
-def _export_documents_as_files(
-    conv_results: Iterable[ConversionResult],
-    output_dir: Path,
-    export_json: bool,
-    export_html: bool,
-    export_md: bool,
-    export_txt: bool,
-    export_doctags: bool,
-    image_export_mode: ImageRefMode,
-    md_page_break_placeholder: str,
-) -> ConversionStatus:
-    success_count = 0
-    failure_count = 0
-
-    # Default failure in case results is empty
-    conv_result = ConversionStatus.FAILURE
-
-    artifacts_dir = Path("artifacts/")  # will be relative to the fname
-
-    for conv_res in conv_results:
-        conv_result = conv_res.status
-        if conv_res.status == ConversionStatus.SUCCESS:
-            success_count += 1
-            doc_filename = conv_res.input.file.stem
-
-            # Export JSON format:
-            if export_json:
-                fname = output_dir / f"{doc_filename}.json"
-                _log.info(f"writing JSON output to {fname}")
-                conv_res.document.save_as_json(
-                    filename=fname,
-                    image_mode=image_export_mode,
-                    artifacts_dir=artifacts_dir,
-                )
-
-            # Export HTML format:
-            if export_html:
-                fname = output_dir / f"{doc_filename}.html"
-                _log.info(f"writing HTML output to {fname}")
-                conv_res.document.save_as_html(
-                    filename=fname,
-                    image_mode=image_export_mode,
-                    artifacts_dir=artifacts_dir,
-                )
-
-            # Export Text format:
-            if export_txt:
-                fname = output_dir / f"{doc_filename}.txt"
-                _log.info(f"writing TXT output to {fname}")
-                conv_res.document.save_as_markdown(
-                    filename=fname,
-                    strict_text=True,
-                    image_mode=ImageRefMode.PLACEHOLDER,
-                )
-
-            # Export Markdown format:
-            if export_md:
-                fname = output_dir / f"{doc_filename}.md"
-                _log.info(f"writing Markdown output to {fname}")
-                conv_res.document.save_as_markdown(
-                    filename=fname,
-                    artifacts_dir=artifacts_dir,
-                    image_mode=image_export_mode,
-                    page_break_placeholder=md_page_break_placeholder or None,
-                )
-
-            # Export Document Tags format:
-            if export_doctags:
-                fname = output_dir / f"{doc_filename}.doctags"
-                _log.info(f"writing Doc Tags output to {fname}")
-                conv_res.document.save_as_doctags(filename=fname)
-
-        else:
-            _log.warning(f"Document {conv_res.input.file} failed to convert.")
-            failure_count += 1
-
-    _log.info(
-        f"Processed {success_count + failure_count} docs, "
-        f"of which {failure_count} failed"
-    )
-    return conv_result
-
-
-def process_results(
-    conversion_options: ConvertDocumentsOptions,
-    target: TaskTarget,
-    conv_results: Iterable[ConversionResult],
-    work_dir: Path,
-) -> Union[ConvertDocumentResponse, FileResponse, PresignedUrlConvertDocumentResponse]:
-    # Let's start by processing the documents
-    try:
-        start_time = time.monotonic()
-
-        # Convert the iterator to a list to count the number of results and get timings
-        # As it's an iterator (lazy evaluation), it will also start the conversion
-        conv_results = list(conv_results)
-
-        processing_time = time.monotonic() - start_time
-
-        _log.info(
-            f"Processed {len(conv_results)} docs in {processing_time:.2f} seconds."
-        )
-
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=str(e))
-
-    if len(conv_results) == 0:
-        raise HTTPException(
-            status_code=500, detail="No documents were generated by Docling."
-        )
-
-    # We have some results, let's prepare the response
-    response: Union[
-        FileResponse, ConvertDocumentResponse, PresignedUrlConvertDocumentResponse
-    ]
-
-    # Booleans to know what to export
-    export_json = OutputFormat.JSON in conversion_options.to_formats
-    export_html = OutputFormat.HTML in conversion_options.to_formats
-    export_md = OutputFormat.MARKDOWN in conversion_options.to_formats
-    export_txt = OutputFormat.TEXT in conversion_options.to_formats
-    export_doctags = OutputFormat.DOCTAGS in conversion_options.to_formats
-
-    # Only 1 document was processed, and we are not returning it as a file
-    if len(conv_results) == 1 and isinstance(target, InBodyTarget):
-        conv_res = conv_results[0]
-        document = _export_document_as_content(
-            conv_res,
-            export_json=export_json,
-            export_html=export_html,
-            export_md=export_md,
-            export_txt=export_txt,
-            export_doctags=export_doctags,
-            image_mode=conversion_options.image_export_mode,
-            md_page_break_placeholder=conversion_options.md_page_break_placeholder,
-        )
-
-        response = ConvertDocumentResponse(
-            document=document,
-            status=conv_res.status,
-            processing_time=processing_time,
-            timings=conv_res.timings,
-        )
-
-    # Multiple documents were processed, or we are forced returning as a file
-    else:
-        # Temporary directory to store the outputs
-        output_dir = work_dir / "output"
-        output_dir.mkdir(parents=True, exist_ok=True)
-
-        # Worker pid to use in archive identification as we may have multiple workers
-        os.getpid()
-
-        # Export the documents
-        conv_result = _export_documents_as_files(
-            conv_results=conv_results,
-            output_dir=output_dir,
-            export_json=export_json,
-            export_html=export_html,
-            export_md=export_md,
-            export_txt=export_txt,
-            export_doctags=export_doctags,
-            image_export_mode=conversion_options.image_export_mode,
-            md_page_break_placeholder=conversion_options.md_page_break_placeholder,
-        )
-
-        files = os.listdir(output_dir)
-        if len(files) == 0:
-            raise HTTPException(status_code=500, detail="No documents were exported.")
-
-        file_path = work_dir / "converted_docs.zip"
-        shutil.make_archive(
-            base_name=str(file_path.with_suffix("")),
-            format="zip",
-            root_dir=output_dir,
-        )
-
-        # Other cleanups after the response is sent
-        # Output directory
-        # background_tasks.add_task(shutil.rmtree, work_dir, ignore_errors=True)
-
-        if isinstance(target, PutTarget):
-            try:
-                with open(file_path, "rb") as file_data:
-                    r = httpx.put(str(target.url), files={"file": file_data})
-                    r.raise_for_status()
-                response = PresignedUrlConvertDocumentResponse(
-                    status=conv_result,
-                    processing_time=processing_time,
-                )
-            except Exception as exc:
-                _log.error("An error occour while uploading zip to s3", exc_info=exc)
-                raise HTTPException(
-                    status_code=500, detail="An error occour while uploading zip to s3."
-                )
-        else:
-            response = FileResponse(
-                file_path, filename=file_path.name, media_type="application/zip"
-            )
-
-    return response
-
-
 async def prepare_response(
-    task: Task, orchestrator: BaseOrchestrator, background_tasks: BackgroundTasks
+    task_id: str,
+    task_result: ConvertDocumentResult,
+    orchestrator: BaseOrchestrator,
+    background_tasks: BackgroundTasks,
 ):
-    if task.results is None:
-        raise HTTPException(
-            status_code=404,
-            detail="Task result not found. Please wait for a completion status.",
+    response: Response | ConvertDocumentResponse | PresignedUrlConvertDocumentResponse
+    if isinstance(task_result.result, ExportResult):
+        response = ConvertDocumentResponse(
+            document=task_result.result.content,
+            status=task_result.result.status,
+            processing_time=task_result.processing_time,
+            timings=task_result.result.timings,
+            errors=task_result.result.errors,
         )
-    assert task.options is not None
-
-    work_dir = get_scratch() / task.task_id
-    response = process_results(
-        conversion_options=task.options,
-        target=task.target,
-        conv_results=task.results,
-        work_dir=work_dir,
-    )
-
-    if work_dir.exists():
-        task.scratch_dir = work_dir
-        if not isinstance(response, FileResponse):
-            _log.warning(
-                f"Task {task.task_id=} produced content in {work_dir=} but the response is not a file."
-            )
-            shutil.rmtree(work_dir, ignore_errors=True)
+    elif isinstance(task_result.result, ZipArchiveResult):
+        response = Response(
+            content=task_result.result.content,
+            media_type="application/zip",
+            headers={
+                "Content-Disposition": 'attachment; filename="converted_docs.zip"'
+            },
+        )
+    elif isinstance(task_result.result, RemoteTargetResult):
+        response = PresignedUrlConvertDocumentResponse(
+            processing_time=task_result.processing_time,
+            num_converted=task_result.num_converted,
+            num_succeeded=task_result.num_succeeded,
+            num_failed=task_result.num_failed,
+        )
+    else:
+        raise ValueError("Unknown result type")
 
     if docling_serve_settings.single_use_results:
-        if task.scratch_dir is not None:
-            background_tasks.add_task(
-                shutil.rmtree, task.scratch_dir, ignore_errors=True
-            )
 
         async def _remove_task_impl():
             await asyncio.sleep(docling_serve_settings.result_removal_delay)
-            await orchestrator.delete_task(task_id=task.task_id)
+            await orchestrator.delete_task(task_id=task_id)
 
         async def _remove_task():
             asyncio.create_task(_remove_task_impl())  # noqa: RUF006

docling_serve/settings.py

@@ -28,6 +28,7 @@ class UvicornSettings(BaseSettings):
 class AsyncEngine(str, enum.Enum):
     LOCAL = "local"
     KFP = "kfp"
+    RQ = "rq"
 
 
 class DoclingServeSettings(BaseSettings):
@@ -50,6 +51,8 @@ class DoclingServeSettings(BaseSettings):
     enable_remote_services: bool = False
     allow_external_plugins: bool = False
 
+    api_key: str = ""
+
     max_document_timeout: float = 3_600 * 24 * 7  # 7 days
     max_num_pages: int = sys.maxsize
     max_file_size: int = sys.maxsize
@@ -64,6 +67,10 @@ class DoclingServeSettings(BaseSettings):
     # Local engine
     eng_loc_num_workers: int = 2
     eng_loc_share_models: bool = False
+    # RQ engine
+    eng_rq_redis_url: str = ""
+    eng_rq_results_prefix: str = "docling:results"
+    eng_rq_sub_channel: str = "docling:updates"
     # KFP engine
     eng_kfp_endpoint: Optional[AnyUrl] = None
     eng_kfp_token: Optional[str] = None
@@ -87,6 +94,10 @@ class DoclingServeSettings(BaseSettings):
                     "KFP is not yet working. To enable the development version, you must set DOCLING_SERVE_ENG_KFP_EXPERIMENTAL=true."
                 )
 
+        if self.eng_kind == AsyncEngine.RQ:
+            if not self.eng_rq_redis_url:
+                raise ValueError("RQ Redis url is required when using the RQ engine.")
+
         return self
 
 

docs/README.md

@@ -3,7 +3,8 @@
 This documentation pages explore the webserver configurations, runtime options, deployment examples as well as development best practices.
 
 - [Configuration](./configuration.md)
-- [Advance usage](./usage.md)
+- [Handling models](./models.md)
+- [Usage](./usage.md)
 - [Deployment](./deployment.md)
 - [Development](./development.md)
 - [`v1` migration](./v1_migration.md)

docs/configuration.md

@@ -52,7 +52,8 @@ THe following table describes the options to configure the Docling Serve app.
 |  | `DOCLING_SERVE_CORS_ORIGINS` | `["*"]` | A list of origins that should be permitted to make cross-origin requests. |
 |  | `DOCLING_SERVE_CORS_METHODS` | `["*"]` | A list of HTTP methods that should be allowed for cross-origin requests. |
 |  | `DOCLING_SERVE_CORS_HEADERS` | `["*"]` | A list of HTTP request headers that should be supported for cross-origin requests. |
-|  | `DOCLING_SERVE_ENG_KIND` | `local` | The compute engine to use for the async tasks. Possible values are `local` and `kfp`. See below for more configurations of the engines. |
+|  | `DOCLING_SERVE_ENG_API_KEY` | | If specified, all the API requests must contain the header `X-Api-Key` with this value. |
+|  | `DOCLING_SERVE_ENG_KIND` | `local` | The compute engine to use for the async tasks. Possible values are `local`, `rq` and `kfp`. See below for more configurations of the engines. |
 
 ### Compute engine
 
@@ -68,6 +69,16 @@ The following table describes the options to configure the Docling Serve local e
 | `DOCLING_SERVE_ENG_LOC_NUM_WORKERS` | 2 | Number of workers/threads processing the incoming tasks. |
 | `DOCLING_SERVE_ENG_LOC_SHARE_MODELS` | False | If true, each process will share the same models among all thread workers. Otherwise, one instance of the models is allocated for each worker thread. |
 
+#### RQ engine
+
+The following table describes the options to configure the Docling Serve RQ engine.
+
+| ENV | Default | Description |
+|-----|---------|-------------|
+| `DOCLING_SERVE_ENG_RQ_REDIS_URL` | (required) | The connection Redis url, e.g. `redis://localhost:6373/` |
+| `DOCLING_SERVE_ENG_RQ_RESULTS_PREFIX` | `docling:results` | The prefix used for storing the results in Redis. |
+| `DOCLING_SERVE_ENG_RQ_RESULTS_PREFIX` | `docling:updates` | The channel key name used for storing communicating updates between the workers and the orchestrator. |
+
 #### KFP engine
 
 The following table describes the options to configure the Docling Serve KFP engine.
@@ -80,3 +91,10 @@ The following table describes the options to configure the Docling Serve KFP eng
 | `DOCLING_SERVE_ENG_KFP_SELF_CALLBACK_ENDPOINT` |  | If set, it enables internal callbacks providing status update of the KFP job. Usually something like `https://NAME.NAMESPACE.svc.cluster.local:5001/v1/callback/task/progress`. |
 | `DOCLING_SERVE_ENG_KFP_SELF_CALLBACK_TOKEN_PATH` |  | The token used for authenticating the progress callback. For cluster-internal workloads, use `/run/secrets/kubernetes.io/serviceaccount/token`. |
 | `DOCLING_SERVE_ENG_KFP_SELF_CALLBACK_CA_CERT_PATH` |  | The CA certificate for the progress callback. For cluster-inetrnal workloads, use `/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt`. |
+
+#### Gradio UI
+
+When using Gradio UI and using the option to output conversion as file, Gradio uses cache to prevent files to be overwritten ([more info here](https://www.gradio.app/guides/file-access#the-gradio-cache)), and we defined the cache clean frequency of one hour to clean files older than 10hours. For situations that files need to be available to download from UI older than 10 hours, there is two options:
+
+- Increase the older age of files to clean [here](https://github.com/docling-project/docling-serve/blob/main/docling_serve/gradio_ui.py#L483) to suffice the age desired;
+- Or set the clean up manually by defining the temporary dir of Gradio to use the same as `DOCLING_SERVE_SCRATCH_PATH` absolute path. This can be achieved by setting the environment variable `GRADIO_TEMP_DIR`, that can be done via command line `export GRADIO_TEMP_DIR="<same_path_as_scratch>"` or in `Dockerfile` using `ENV GRADIO_TEMP_DIR="<same_path_as_scratch>"`. After this, set the clean of cache to `None` [here](https://github.com/docling-project/docling-serve/blob/main/docling_serve/gradio_ui.py#L483). Now, the clean up of `DOCLING_SERVE_SCRATCH_PATH` will also clean the Gradio temporary dir. (If you use this option, please remember when reversing changes to remove the environment variable `GRADIO_TEMP_DIR`, otherwise may lead to files not be available to download).

docs/deploy-examples/docling-serve-rq-workers.yaml

@@ -0,0 +1,192 @@
+# This example deployment configures Docling Serve with a Service and RQ workers
+
+# Create following secret
+# kubectl create secret generic docling-serve-rq-secrets --from-literal=REDIS_PASSWORD=myredispassword --from-literal=RQ_REDIS_URL=redis://:myredispassword@docling-serve-redis-service:6373/
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: docling-serve
+  labels:
+    app: docling-serve
+    component: docling-serve-api
+spec:
+  ports:
+  - name: http
+    port: 5001
+    targetPort: http
+  selector:
+    app: docling-serve
+    component: docling-serve-api
+---
+kind: Deployment
+apiVersion: apps/v1
+metadata:
+  name: docling-serve
+  labels:
+    app: docling-serve
+    component: docling-serve-api
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: docling-serve
+      component: docling-serve-api
+  template:
+    metadata:
+      labels:
+        app: docling-serve
+        component: docling-serve-api
+    spec:
+      restartPolicy: Always
+      containers:
+        - name: api
+          resources:
+            limits:
+              cpu: 1
+              memory: 8Gi
+            requests:
+              cpu: 250m
+              memory: 1Gi
+          env:
+            - name: DOCLING_SERVE_ENABLE_UI
+              value: 'true'
+            - name: DOCLING_SERVE_ENG_KIND
+              value: 'rq'
+            - name: DOCLING_SERVE_ENG_RQ_REDIS_URL
+              valueFrom:
+                secretKeyRef:
+                  name: docling-serve-rq-secrets
+                  key: RQ_REDIS_URL
+          ports:
+            - name: http
+              containerPort: 5001
+              protocol: TCP
+          imagePullPolicy: Always
+          image: 'ghcr.io/docling-project/docling-serve-cpu'
+---
+kind: Deployment
+apiVersion: apps/v1
+metadata:
+  name: docling-serve-rq-workers
+  labels:
+    app: docling-serve-rq-workers
+    component: docling-serve-rq-worker
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: docling-serve-rq-workers
+      component: docling-serve-rq-worker
+  template:
+    metadata:
+      labels:
+        app: docling-serve-rq-workers
+        component: docling-serve-rq-worker
+    spec:
+      restartPolicy: Always
+      containers:
+        - name: worker
+          resources:
+            limits:
+              cpu: 1
+              memory: 4Gi
+            requests:
+              cpu: 250m
+              memory: 1Gi
+          env:
+            - name: DOCLING_SERVE_ENG_KIND
+              value: 'rq'
+            - name: DOCLING_SERVE_ENG_RQ_REDIS_URL
+              valueFrom:
+                secretKeyRef:
+                  name: docling-serve-rq-secrets
+                  key: RQ_REDIS_URL
+          ports:
+            - name: http
+              containerPort: 5001
+              protocol: TCP
+          imagePullPolicy: Always
+          image: 'ghcr.io/docling-project/docling-serve-cpu'
+          command: ["docling-serve"]
+          args: ["rq-worker"]
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: docling-serve-redis
+  labels:
+    app: docling-serve-redis
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: docling-serve-redis
+  template:
+    metadata:
+      labels:
+        app: docling-serve-redis
+    spec:
+      restartPolicy: Always
+      terminationGracePeriodSeconds: 30
+      containers:
+        - name: redis
+          resources:
+            limits:
+              cpu: 1
+              memory: 1Gi
+            requests:
+              cpu: 250m
+              memory: 100Mi
+          image: redis:latest
+          command: ["redis-server"]
+          args:
+            - "--port"
+            - "6373"
+            - "--dir"
+            - "/mnt/redis/data"
+            - "--appendonly"
+            - "yes"
+            - "--requirepass"
+            - "$(REDIS_PASSWORD)"
+          ports:
+            - containerPort: 6373
+          env:
+            - name: REDIS_PASSWORD
+              valueFrom:
+                secretKeyRef:
+                  name: docling-serve-rq-secrets
+                  key: REDIS_PASSWORD
+          volumeMounts:
+            - name: redis-data
+              mountPath: /mnt/redis/data
+          securityContext:
+            fsGroup: 1004
+            runAsNonRoot: true
+            allowPrivilegeEscalation: false
+            capabilities:
+              drop:
+                - ALL
+            seccompProfile:
+              type: RuntimeDefault
+      volumes:
+        - name: redis-data
+          emptyDir:
+            medium: Memory
+            sizeLimit: 2Gi
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: docling-serve-redis-service
+  labels:
+      app: docling-serve-redis
+spec:
+  type: NodePort
+  ports:
+    - name: redis-service
+      protocol: TCP
+      port: 6373
+      targetPort: 6373
+  selector:
+    app: docling-serve-redis

docs/deployment.md

@@ -225,6 +225,31 @@ curl -X 'POST' \
   }'
 ```
 
+### Multiple workers with RQ
+
+Manifest example: [`docling-serve-rq-workers.yaml`](./deploy-examples/docling-serve-rq-workers.yaml)
+
+This deployment example has the following features:
+
+- Deployment configuration
+- Service configuration
+- Redis deployment
+- Multiple (2 by default) worker Pods
+
+Install the app with:
+
+- create k8s secret:
+
+```sh
+kubectl create secret generic docling-serve-rq-secrets --from-literal=REDIS_PASSWORD=myredispassword --from-literal=RQ_REDIS_URL=redis://:myredispassword@docling-serve-redis-service:6373/
+```
+
+- apply deployment manifest:
+
+```sh
+oc apply -f docs/deploy-examples/docling-serve-rq-workers.yaml
+```
+
 ### Secure deployment with `oauth-proxy`
 
 Manifest example: [docling-serve-oauth.yaml](./deploy-examples/docling-serve-oauth.yaml)

docs/models.md

@@ -0,0 +1,175 @@
+# Handling Models in Docling Serve
+
+When enabling steps in Docling Serve that require extra models (such as picture classification, picture description, table detection, code recognition, formula extraction, or vision-language modules), you must ensure those models are available in the runtime environment. The standard container image includes only the default models. Any additional models must be downloaded and made available before use. If required models are missing, Docling Serve will raise runtime errors rather than downloading them automatically. This default choice wants to guarantee the system is not calling external services.
+
+## Model Storage Location
+
+Docling Serve loads models from the directory specified by the `DOCLING_SERVE_ARTIFACTS_PATH` environment variable. This path must be consistent across model download and runtime. When running with multiple workers or reload enabled, you must use the environment variable rather than the CLI argument for configuration [[source]](./configuration.md).
+
+## Approaches for Making Extra Models Available
+
+There are several ways to ensure required models are present:
+
+### 1. Disable Local Models (Trigger Auto-Download)
+
+You can configure the container to download all models at startup by clearing the artifacts path:
+
+```sh
+podman run -d -p 5001:5001 --name docling-serve \
+  -e DOCLING_SERVE_ARTIFACTS_PATH="" \
+  -e DOCLING_SERVE_ENABLE_UI=true \
+  quay.io/docling-project/docling-serve
+```
+
+This approach is simple for local development but not recommended for production, as it increases startup time and depends on network availability.
+
+### 2. Build a Custom Image with Pre-Downloaded Models
+
+You can create a new image that includes the required models:
+
+```Dockerfile
+FROM quay.io/docling-project/docling-serve
+RUN docling-tools models download smolvlm
+```
+
+This method is suitable for production, as it ensures all models are present in the image and avoids runtime downloads.
+
+### 3. Update the Entrypoint to Download Models Before Startup
+
+You can override the entrypoint to download models before starting the service:
+
+```sh
+podman run -p 5001:5001 -e DOCLING_SERVE_ENABLE_UI=true \
+  quay.io/docling-project/docling-serve \
+  -- sh -c 'exec docling-tools models download smolvlm && exec docling-serve run'
+```
+
+This is useful for environments where you want to keep the base image unchanged but still automate model preparation.
+
+### 4. Mount a Volume with Pre-Downloaded Models
+
+Download models locally and mount them into the container:
+
+```sh
+# Download the models locally
+docling-tools models download --all -o models
+
+# Start the container with the local models folder
+podman run -p 5001:5001 \
+  -v $(pwd)/models:/opt/app-root/src/models \
+  -e DOCLING_SERVE_ARTIFACTS_PATH="/opt/app-root/src/models" \
+  -e DOCLING_SERVE_ENABLE_UI=true \
+  quay.io/docling-project/docling-serve
+```
+
+This approach is robust for both local and production deployments, especially when using persistent storage.
+
+## Kubernetes/Cluster Deployments
+
+For Kubernetes or OpenShift clusters, the recommended approach is to use a PersistentVolumeClaim (PVC) for model storage, a Kubernetes Job to download models, and mount the volume into the deployment. This ensures models persist across pod restarts and scale-out scenarios.
+
+### Example: PersistentVolumeClaim
+
+```yaml
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: docling-model-cache-pvc
+spec:
+  accessModes:
+    - ReadWriteOnce
+  volumeMode: Filesystem
+  resources:
+    requests:
+      storage: 10Gi
+```
+
+If you don't want to use default storage class, set your custom storage class with following:
+
+```yaml
+spec:
+    ...
+    storageClassName: <Storage Class Name>
+```
+
+Manifest example: [docling-model-cache-pvc.yaml](./deploy-examples/docling-model-cache-pvc.yaml)
+
+### Example: Model Download Job
+
+```yaml
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: docling-model-cache-load
+spec:
+  template:
+    spec:
+      containers:
+        - name: loader
+          image: ghcr.io/docling-project/docling-serve-cpu:main
+          command:
+            - docling-tools
+            - models
+            - download
+            - '--output-dir=/modelcache'
+            - 'layout'
+            - 'tableformer'
+            - 'code_formula'
+            - 'picture_classifier'
+            - 'smolvlm'
+            - 'granite_vision'
+            - 'easyocr'
+          volumeMounts:
+            - name: docling-model-cache
+              mountPath: /modelcache
+      volumes:
+        - name: docling-model-cache
+          persistentVolumeClaim:
+            claimName: docling-model-cache-pvc
+      restartPolicy: Never
+```
+
+The job will mount the previously created persistent volume and execute command similar to how we would load models locally:
+`docling-tools models download --output-dir <MOUNT-PATH> [LIST_OF_MODELS]`
+
+In manifest, we specify desired models individually, or we can use `--all` parameter to download all models.
+
+Manifest example: [docling-model-cache-job.yaml](./deploy-examples/docling-model-cache-job.yaml)
+
+### Example: Deployment with Mounted Volume
+
+```yaml
+spec:
+  template:
+    spec:
+      containers:
+        - name: api
+          env:
+            - name: DOCLING_SERVE_ARTIFACTS_PATH
+              value: '/modelcache'
+          volumeMounts:
+            - name: docling-model-cache
+              mountPath: /modelcache
+      volumes:
+        - name: docling-model-cache
+          persistentVolumeClaim:
+            claimName: docling-model-cache-pvc
+```
+
+The value of `DOCLING_SERVE_ARTIFACTS_PATH` must match the mount path where models are stored.
+
+Now, when docling-serve is executing tasks, the underlying docling installation will load model weights from mounted volume.
+
+Manifest example: [docling-model-cache-deployment.yaml](./deploy-examples/docling-model-cache-deployment.yaml)
+
+## Local Docker Execution
+
+For local Docker or Podman execution, you can use any of the approaches above. Mounting a local directory with pre-downloaded models is the most reliable for repeated runs and avoids network dependencies.
+
+## Troubleshooting and Best Practices
+
+- If a required model is missing from the artifacts path, Docling Serve will raise a runtime error.
+- Always ensure the value of `DOCLING_SERVE_ARTIFACTS_PATH` matches the directory where models are stored and mounted.
+- For production and cluster environments, prefer persistent storage and pre-loading models via a dedicated job.
+
+For more details and YAML manifest examples, see the [deployment documentation](./deployment.md).

docs/pre-loading-models.md

@@ -1,103 +0,0 @@
-# Pre-loading models for docling
-
-This document provides examples for pre-loading docling models to a persistent volume and re-using it for docling-serve deployments.
-
-1. We need to create a persistent volume that will store models weights:
-
-    ```yaml
-    apiVersion: v1
-    kind: PersistentVolumeClaim
-    metadata:
-      name: docling-model-cache-pvc
-    spec:
-      accessModes:
-        - ReadWriteOnce
-      volumeMode: Filesystem
-      resources:
-        requests:
-          storage: 10Gi
-    ```
-
-    If you don't want to use default storage class, set your custom storage class with following:
-
-    ```yaml
-    spec:
-      ...
-      storageClassName: <Storage Class Name>
-    ```
-
-    Manifest example: [docling-model-cache-pvc.yaml](./deploy-examples/docling-model-cache-pvc.yaml)
-
-2. In order to load model weights, we can use docling-toolkit to download them, as this is a one time operation we can use kubernetes job for this:
-
-    ```yaml
-    apiVersion: batch/v1
-    kind: Job
-    metadata:
-      name: docling-model-cache-load
-    spec:
-      selector: {}
-      template:
-        metadata:
-          name: docling-model-load
-        spec:
-          containers:
-            - name: loader
-              image: ghcr.io/docling-project/docling-serve-cpu:main
-              command:
-                - docling-tools
-                - models
-                - download
-                - '--output-dir=/modelcache'
-                - 'layout'
-                - 'tableformer'
-                - 'code_formula'
-                - 'picture_classifier'
-                - 'smolvlm'
-                - 'granite_vision'
-                - 'easyocr'
-              volumeMounts:
-                - name: docling-model-cache
-                  mountPath: /modelcache
-          volumes:
-            - name: docling-model-cache
-              persistentVolumeClaim:
-                claimName: docling-model-cache-pvc
-          restartPolicy: Never
-    ```
-
-    The job will mount previously created persistent volume and execute command similar to how we would load models locally:
-    `docling-tools models download --output-dir <MOUNT-PATH> [LIST_OF_MODELS]`
-
-    In manifest, we specify desired models individually, or we can use `--all` parameter to download all models.
-
-    Manifest example: [docling-model-cache-job.yaml](./deploy-examples/docling-model-cache-job.yaml)
-
-3. Now we can mount volume in the docling-serve deployment and set env `DOCLING_SERVE_ARTIFACTS_PATH` to point to it.
-    Following additions to deployment should be made:
-
-    ```yaml
-    spec:
-      template:
-        spec:
-          containers:
-            - name: api
-              env:
-              ...
-                - name: DOCLING_SERVE_ARTIFACTS_PATH
-                  value: '/modelcache'
-              volumeMounts:
-                - name: docling-model-cache
-                  mountPath: /modelcache
-          ...
-          volumes:
-            - name: docling-model-cache
-              persistentVolumeClaim:
-                claimName: docling-model-cache-pvc
-    ```
-
-    Make sure that value of `DOCLING_SERVE_ARTIFACTS_PATH` is the same as where models were downloaded and where volume is mounted.
-
-    Now when docling-serve is executing tasks, the underlying docling installation will load model weights from mounted volume.
-
-    Manifest example: [docling-model-cache-deployment.yaml](./deploy-examples/docling-model-cache-deployment.yaml)

docs/usage.md

@@ -30,6 +30,10 @@ On top of the source of file (see below), both endpoints support the same parame
 - `include_images` (bool): If enabled, images will be extracted from the document. Defaults to false.
 - `images_scale` (float): Scale factor for images. Defaults to 2.0.
 
+### Authentication
+
+When authentication is activated (see the parameter `DOCLING_SERVE_ENG_API_KEY` in [configuration.md](./configuration.md)), all the API requests **must** provide the header `X-Api-Key` with the correct secret key.
+
 ## Convert endpoints
 
 ### Source endpoint

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docling-serve"
-version = "1.2.1"  # DO NOT EDIT, updated automatically
+version = "1.3.0"  # DO NOT EDIT, updated automatically
 description = "Running Docling as a service"
 license = {text = "MIT"}
 authors = [
@@ -35,7 +35,7 @@ requires-python = ">=3.10"
 dependencies = [
     "docling~=2.38",
     "docling-core>=2.44.1",
-    "docling-jobkit[kfp,vlm]>=1.3.1,<2.0.0",
+    "docling-jobkit[kfp,rq,vlm]>=1.4.0,<2.0.0",
     "fastapi[standard]~=0.115",
     "httpx~=0.28",
     "pydantic~=2.10",

tests/test_1-file-all-outputs.py

@@ -6,10 +6,15 @@ import pytest
 import pytest_asyncio
 from pytest_check import check
 
+from docling_serve.settings import docling_serve_settings
+
 
 @pytest_asyncio.fixture
 async def async_client():
-    async with httpx.AsyncClient(timeout=60.0) as client:
+    headers = {}
+    if docling_serve_settings.api_key:
+        headers["X-Api-Key"] = docling_serve_settings.api_key
+    async with httpx.AsyncClient(timeout=60.0, headers=headers) as client:
         yield client
 
 

tests/test_1-file-async.py

@@ -6,10 +6,15 @@ import httpx
 import pytest
 import pytest_asyncio
 
+from docling_serve.settings import docling_serve_settings
+
 
 @pytest_asyncio.fixture
 async def async_client():
-    async with httpx.AsyncClient(timeout=60.0) as client:
+    headers = {}
+    if docling_serve_settings.api_key:
+        headers["X-Api-Key"] = docling_serve_settings.api_key
+    async with httpx.AsyncClient(timeout=60.0, headers=headers) as client:
         yield client
 
 

tests/test_1-url-all-outputs.py

@@ -5,10 +5,15 @@ import pytest
 import pytest_asyncio
 from pytest_check import check
 
+from docling_serve.settings import docling_serve_settings
+
 
 @pytest_asyncio.fixture
 async def async_client():
-    async with httpx.AsyncClient(timeout=60.0) as client:
+    headers = {}
+    if docling_serve_settings.api_key:
+        headers["X-Api-Key"] = docling_serve_settings.api_key
+    async with httpx.AsyncClient(timeout=60.0, headers=headers) as client:
         yield client
 
 

tests/test_1-url-async-ws.py

@@ -6,16 +6,24 @@ import pytest
 import pytest_asyncio
 from websockets.sync.client import connect
 
+from docling_serve.settings import docling_serve_settings
+
 
 @pytest_asyncio.fixture
 async def async_client():
-    async with httpx.AsyncClient(timeout=60.0) as client:
+    headers = {}
+    if docling_serve_settings.api_key:
+        headers["X-Api-Key"] = docling_serve_settings.api_key
+    async with httpx.AsyncClient(timeout=60.0, headers=headers) as client:
         yield client
 
 
 @pytest.mark.asyncio
 async def test_convert_url(async_client: httpx.AsyncClient):
     """Test convert URL to all outputs"""
+    headers = {}
+    if docling_serve_settings.api_key:
+        headers["X-Api-Key"] = docling_serve_settings.api_key
 
     doc_filename = Path("tests/2408.09869v5.pdf")
     encoded_doc = base64.b64encode(doc_filename.read_bytes()).decode()
@@ -57,7 +65,7 @@ async def test_convert_url(async_client: httpx.AsyncClient):
 
     task = response.json()
 
-    uri = f"ws://localhost:5001/v1/status/ws/{task['task_id']}"
+    uri = f"ws://localhost:5001/v1/status/ws/{task['task_id']}?api_key={docling_serve_settings.api_key}"
     with connect(uri) as websocket:
         for message in websocket:
             print(message)

tests/test_1-url-async.py

@@ -6,10 +6,15 @@ import httpx
 import pytest
 import pytest_asyncio
 
+from docling_serve.settings import docling_serve_settings
+
 
 @pytest_asyncio.fixture
 async def async_client():
-    async with httpx.AsyncClient(timeout=60.0) as client:
+    headers = {}
+    if docling_serve_settings.api_key:
+        headers["X-Api-Key"] = docling_serve_settings.api_key
+    async with httpx.AsyncClient(timeout=60.0, headers=headers) as client:
         yield client
 
 

tests/test_2-files-all-outputs.py

@@ -5,10 +5,15 @@ import pytest
 import pytest_asyncio
 from pytest_check import check
 
+from docling_serve.settings import docling_serve_settings
+
 
 @pytest_asyncio.fixture
 async def async_client():
-    async with httpx.AsyncClient(timeout=60.0) as client:
+    headers = {}
+    if docling_serve_settings.api_key:
+        headers["X-Api-Key"] = docling_serve_settings.api_key
+    async with httpx.AsyncClient(timeout=60.0, headers=headers) as client:
         yield client
 
 

tests/test_2-urls-all-outputs.py

@@ -3,10 +3,15 @@ import pytest
 import pytest_asyncio
 from pytest_check import check
 
+from docling_serve.settings import docling_serve_settings
+
 
 @pytest_asyncio.fixture
 async def async_client():
-    async with httpx.AsyncClient(timeout=60.0) as client:
+    headers = {}
+    if docling_serve_settings.api_key:
+        headers["X-Api-Key"] = docling_serve_settings.api_key
+    async with httpx.AsyncClient(timeout=60.0, headers=headers) as client:
         yield client
 
 

tests/test_2-urls-async-all-outputs.py

@@ -6,10 +6,15 @@ import pytest
 import pytest_asyncio
 from pytest_check import check
 
+from docling_serve.settings import docling_serve_settings
+
 
 @pytest_asyncio.fixture
 async def async_client():
-    async with httpx.AsyncClient(timeout=60.0) as client:
+    headers = {}
+    if docling_serve_settings.api_key:
+        headers["X-Api-Key"] = docling_serve_settings.api_key
+    async with httpx.AsyncClient(timeout=60.0, headers=headers) as client:
         yield client
 
 

tests/test_fastapi_endpoints.py

@@ -13,6 +13,7 @@ from pytest_check import check
 from docling_core.types.doc import DoclingDocument, PictureItem
 
 from docling_serve.app import create_app
+from docling_serve.settings import docling_serve_settings
 
 
 @pytest.fixture(scope="session")
@@ -20,6 +21,14 @@ def event_loop():
     return asyncio.get_event_loop()
 
 
+@pytest.fixture(scope="session")
+def auth_headers():
+    headers = {}
+    if docling_serve_settings.api_key:
+        headers["X-Api-Key"] = docling_serve_settings.api_key
+    return headers
+
+
 @pytest_asyncio.fixture(scope="session")
 async def app():
     app = create_app()
@@ -46,7 +55,7 @@ async def test_health(client: AsyncClient):
 
 
 @pytest.mark.asyncio
-async def test_convert_file(client: AsyncClient):
+async def test_convert_file(client: AsyncClient, auth_headers: dict):
     """Test convert single file to all outputs"""
 
     endpoint = "/v1/convert/file"
@@ -79,7 +88,9 @@ async def test_convert_file(client: AsyncClient):
         "files": ("2206.01062v1.pdf", open(file_path, "rb"), "application/pdf"),
     }
 
-    response = await client.post(endpoint, files=files, data=options)
+    response = await client.post(
+        endpoint, files=files, data=options, headers=auth_headers
+    )
     assert response.status_code == 200, "Response should be 200 OK"
 
     data = response.json()
@@ -160,7 +171,7 @@ async def test_convert_file(client: AsyncClient):
 
 
 @pytest.mark.asyncio
-async def test_referenced_artifacts(client: AsyncClient):
+async def test_referenced_artifacts(client: AsyncClient, auth_headers: dict):
     """Test that paths in the zip file are relative to the zip file root."""
 
     endpoint = "/v1/convert/file"
@@ -178,7 +189,9 @@ async def test_referenced_artifacts(client: AsyncClient):
         "files": ("2206.01062v1.pdf", open(file_path, "rb"), "application/pdf"),
     }
 
-    response = await client.post(endpoint, files=files, data=options)
+    response = await client.post(
+        endpoint, files=files, data=options, headers=auth_headers
+    )
     assert response.status_code == 200, "Response should be 200 OK"
 
     with zipfile.ZipFile(io.BytesIO(response.content)) as zip_file:

tests/test_file_opts.py

@@ -11,6 +11,7 @@ from docling_core.types import DoclingDocument
 from docling_core.types.doc.document import PictureDescriptionData
 
 from docling_serve.app import create_app
+from docling_serve.settings import docling_serve_settings
 
 
 @pytest.fixture(scope="session")
@@ -18,6 +19,14 @@ def event_loop():
     return asyncio.get_event_loop()
 
 
+@pytest.fixture(scope="session")
+def auth_headers():
+    headers = {}
+    if docling_serve_settings.api_key:
+        headers["X-Api-Key"] = docling_serve_settings.api_key
+    return headers
+
+
 @pytest_asyncio.fixture(scope="session")
 async def app():
     app = create_app()
@@ -37,7 +46,7 @@ async def client(app):
 
 
 @pytest.mark.asyncio
-async def test_convert_file(client: AsyncClient):
+async def test_convert_file(client: AsyncClient, auth_headers: dict):
     """Test convert single file to all outputs"""
 
     endpoint = "/v1/convert/file"
@@ -63,7 +72,9 @@ async def test_convert_file(client: AsyncClient):
         "files": ("2206.01062v1.pdf", open(file_path, "rb"), "application/pdf"),
     }
 
-    response = await client.post(endpoint, files=files, data=options)
+    response = await client.post(
+        endpoint, files=files, data=options, headers=auth_headers
+    )
     assert response.status_code == 200, "Response should be 200 OK"
 
     data = response.json()

tests/test_results_clear.py

@@ -17,6 +17,14 @@ def event_loop():
     return asyncio.get_event_loop()
 
 
+@pytest.fixture(scope="session")
+def auth_headers():
+    headers = {}
+    if docling_serve_settings.api_key:
+        headers["X-Api-Key"] = docling_serve_settings.api_key
+    return headers
+
+
 @pytest_asyncio.fixture(scope="session")
 async def app():
     app = create_app()
@@ -35,7 +43,7 @@ async def client(app):
         yield client
 
 
-async def convert_file(client: AsyncClient):
+async def convert_file(client: AsyncClient, auth_headers: dict):
     doc_filename = Path("tests/2408.09869v5.pdf")
     encoded_doc = base64.b64encode(doc_filename.read_bytes()).decode()
 
@@ -52,7 +60,9 @@ async def convert_file(client: AsyncClient):
         ],
     }
 
-    response = await client.post("/v1/convert/source/async", json=payload)
+    response = await client.post(
+        "/v1/convert/source/async", json=payload, headers=auth_headers
+    )
     assert response.status_code == 200, "Response should be 200 OK"
 
     task = response.json()
@@ -60,7 +70,9 @@ async def convert_file(client: AsyncClient):
     print(json.dumps(task, indent=2))
 
     while task["task_status"] not in ("success", "failure"):
-        response = await client.get(f"/v1/status/poll/{task['task_id']}")
+        response = await client.get(
+            f"/v1/status/poll/{task['task_id']}", headers=auth_headers
+        )
         assert response.status_code == 200, "Response should be 200 OK"
         task = response.json()
         print(f"{task['task_status']=}")
@@ -74,52 +86,62 @@ async def convert_file(client: AsyncClient):
 
 
 @pytest.mark.asyncio
-async def test_clear_results(client: AsyncClient):
+async def test_clear_results(client: AsyncClient, auth_headers: dict):
     """Test removal of task."""
 
     # Set long delay deletion
     docling_serve_settings.result_removal_delay = 100
 
     # Convert and wait for completion
-    task = await convert_file(client)
+    task = await convert_file(client, auth_headers=auth_headers)
 
     # Get result once
-    result_response = await client.get(f"/v1/result/{task['task_id']}")
+    result_response = await client.get(
+        f"/v1/result/{task['task_id']}", headers=auth_headers
+    )
     assert result_response.status_code == 200, "Response should be 200 OK"
     print("Result 1 ok.")
     result = result_response.json()
     assert result["document"]["json_content"]["schema_name"] == "DoclingDocument"
 
     # Get result twice
-    result_response = await client.get(f"/v1/result/{task['task_id']}")
+    result_response = await client.get(
+        f"/v1/result/{task['task_id']}", headers=auth_headers
+    )
     assert result_response.status_code == 200, "Response should be 200 OK"
     print("Result 2 ok.")
     result = result_response.json()
     assert result["document"]["json_content"]["schema_name"] == "DoclingDocument"
 
     # Clear
-    clear_response = await client.get("/v1/clear/results?older_then=0")
+    clear_response = await client.get(
+        "/v1/clear/results?older_then=0", headers=auth_headers
+    )
     assert clear_response.status_code == 200, "Response should be 200 OK"
     print("Clear ok.")
 
     # Get deleted result
-    result_response = await client.get(f"/v1/result/{task['task_id']}")
+    result_response = await client.get(
+        f"/v1/result/{task['task_id']}", headers=auth_headers
+    )
     assert result_response.status_code == 404, "Response should be removed"
     print("Result was no longer found.")
 
 
 @pytest.mark.asyncio
-async def test_delay_remove(client: AsyncClient):
+async def test_delay_remove(client: AsyncClient, auth_headers: dict):
     """Test automatic removal of task with delay."""
 
     # Set short delay deletion
     docling_serve_settings.result_removal_delay = 5
 
     # Convert and wait for completion
-    task = await convert_file(client)
+    task = await convert_file(client, auth_headers=auth_headers)
 
     # Get result once
-    result_response = await client.get(f"/v1/result/{task['task_id']}")
+    result_response = await client.get(
+        f"/v1/result/{task['task_id']}", headers=auth_headers
+    )
     assert result_response.status_code == 200, "Response should be 200 OK"
     print("Result ok.")
     result = result_response.json()
@@ -129,5 +151,7 @@ async def test_delay_remove(client: AsyncClient):
     await asyncio.sleep(10)
 
     # Get deleted result
-    result_response = await client.get(f"/v1/result/{task['task_id']}")
+    result_response = await client.get(
+        f"/v1/result/{task['task_id']}", headers=auth_headers
+    )
     assert result_response.status_code == 404, "Response should be removed"